obikmer/.kilo/plans/1778319532254-eager-panda.md

Plan d'amélioration technique - obiskio

1. Contexte et objectifs

• Objectif : Renforcer la robustesse, la maintenabilité et les performances de la crate obiskio.
• Priorités :
  1. Gestion des erreurs
  2. Optimisation de la mémoire du pool
  3. Robustesse concurrente
  4. Couverture de tests
  5. Documentation

---

2. Axes d'amélioration détaillés

2.1 Gestion des erreurs

• Problème : SKError ne couvre pas tous les cas (format invalide, taille maximale, CRC)
• Actions :
  • Ajouter variante ParseError(String) dans src/error.rs
  • Valider les tailles de SuperKmer avant parsing
  • Remplacer expect() par unwrap_or_else avec messages explicites
  • Documenter chaque variante d’erreur dans le README

2.2 Optimisation du pool de fichiers

• Problème : SKFilePool utilise un Vec<WriteEntry> non contraint et n’effectue pas de nettoyage en cas d’erreur
• Actions :
  • Implémenter un LimitedVec avec limite stricte à MAX_POOL_SIZE
  • Créer clear_memory() qui supprime les entrées orphelines
  • Ajouter evict_lru_threshold() pour éviction proactive
  • Introduire un RwLock pour les opérations de lecture massives

2.3 Robustesse concurrente

• Problème : Risque de deadlocks dans SKFileWriter::write_batch() et SKFileReader::reopen_and_seek()
• Actions :
  • Remplacer Mutex par RwLock pour les accès en lecture
  • Ajouter un compteur de blocage et logs de timeout
  • Utiliser std::thread::park_timeout pour débloquer
  • Insérer debug_assert! sur les états invariants

2.4 Couverture de tests

• Problème : Absence de benchmarks, de tests de migration, de résilience de fichiers corrompus
• Actions :
  • Benchmarks I/O sur 10k+ SuperKmer avec criterion
  • Tests de migration de version de fichier .meta → .v2.meta
  • Tests de corruption volontaire (truncature, inversion de bits)
  • Tests de stress sur pool saturation (100 threads)

2.5 Documentation & exemples

• Actions :
  • Ajouter des examples dans chaque module (# Examples)
  • Documenter la logique LRU avec diagrammes Mermaid
  • Créer un guide « How to recover from eviction »
  • Mettre à jour le README.md avec tableau des variantes d’erreur

---

3. Plan d'exécution (Roadmap)

Sprint	Durée	Livrables clés
S1	2 jours	Refactorisation SKError, ajout de tests unitaires
S2	3 jours	Implémentation clear_memory() + LimitedVec
S3	2 jours	Passage à RwLock, ajout de compteurs de blocage
S4	2 jours	Benchmarks + tests de migration
S5	1 jour	Documentation finale & mise à jour du README

---

4. Dépendances externes

• Mettre à jour niffler vers la version 2.0 (performance compression)
• Évaluer bincode vs serde_json pour les métas (I/O)
• Ajouter dépendance criterion (dev‑dependencies)

---

5. KPI de suivi

• Couverture de tests : ≥85 % des chemins critiques
• Latence moyenne d’écriture : ↓15 % après optimisation du pool
• Taux d’erreurs résolues : 100 % des nouvelles variantes couvertes
• Temps de build CI : ≤5 min pour l’ensemble des benchmarks

---

6. Validation finale

• Revue de code avec cargo clippy -- -D warnings
• Analyse de toxicité avec cargo deny open-source-licenses
• Vérification de la conformité aux standards de naming du projet