v0.1.0-pre.071

kb-core/CHANGELOG.md

@@ -0,0 +1,17 @@
+<!-- file: kb-core/CHANGELOG.md -->
+<!-- version: 1 -->
+
+# CHANGELOG — kb-core
+
+## 0.1.0-pre.071
+
+- réécriture du README pour l’architecture bot3 ;
+- ajout du TODO, du guide d’utilisation et du changelog de crate ;
+- documentation des erreurs partagées et des identités de modules ;
+- ajout d’exemples couvrant les familles d’API publiques.
+
+## 0.1.0-pre.062
+
+- migration des primitives communes vers la crate consolidée `kb-core` ;
+- maintien d’un type d’erreur explicite sans `anyhow` ni `thiserror` ;
+- adaptation aux normes Rust 2024 et Khadhroony bot3.

kb-core/README.md

@@ -1,23 +1,37 @@
 <!-- file: kb-core/README.md -->
-<!-- version: 3 -->
+<!-- version: 4 -->
 
 # kb-core
 
-Ce crate fournit les types minimaux partagés, les erreurs communes et l'identité des modules.
+`kb-core` fournit les primitives minimales partagées par l’ensemble de `khadhroony-bot3`.
 
-## Rôle dans l'écosystème
+## Responsabilités
 
-Ce module fait partie du découpage strict de Khadhroony Bot2. Il doit conserver des dépendances limitées et ne pas contourner les interfaces communes du workspace.
+- type d’erreur explicite commun au workspace ;
+- alias `Result<T>` ;
+- identité stable des modules ;
+- classification des grandes familles de traitement.
 
-## Règles locales
+La crate reste volontairement petite et ne dépend d’aucune couche fonctionnelle supérieure.
 
-- Les commentaires de code restent en anglais.
-- La documentation Markdown reste en français.
-- Les exports publics sont contrôlés depuis `lib.rs` lorsque le crate expose une bibliothèque.
-- Les binaires utilisent `main.rs` avec les attributs Rust obligatoires.
+## API publique
 
-## Erreurs communes
+- `Error` ;
+- `Result<T>` ;
+- `ModuleName` ;
+- `ModuleVersion` ;
+- `ModuleKind`.
 
-`kb-core::Error` est l'enum d'erreur commune du workspace. Elle fournit des familles stables pour configuration, I/O, JSON, tracing, Tauri, HTTP, WebSocket, base de données, état invalide, client non connecté, fonctionnalité non implémentée et erreurs personnalisées.
+Voir [USAGE.md](USAGE.md) pour les exemples.
 
-`kb-core::Error::new(code, message)` reste disponible comme compatibilité courte pendant que les domaines sont progressivement spécialisés.
+## Relations
+
+`kb-core` est utilisée par toutes les crates qui ont besoin d’un contrat d’erreur ou d’une identité de module partagée. Elle ne contient ni configuration, ni transport, ni stockage, ni logique Solana.
+
+## Documentation
+
+- [USAGE.md](USAGE.md)
+- [TODO.md](TODO.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [Architecture générale](../docs/architecture/ARCHITECTURE.md)
+- [Carte des crates](../docs/architecture/CRATE_MAP.md)

kb-core/TODO.md

@@ -0,0 +1,9 @@
+<!-- file: kb-core/TODO.md -->
+<!-- version: 1 -->
+
+# TODO — kb-core
+
+- [ ] Dette technique - réévaluer les variantes génériques de `Error` lorsque les frontières de domaine seront stabilisées.
+- [ ] Dette technique - réduire progressivement l’usage de `Error::Custom` lorsqu’un code d’erreur mérite une famille dédiée.
+- [ ] Documentation - maintenir la correspondance entre les familles d’erreur publiques et les crates qui les utilisent.
+- [ ] Tests - ajouter un test ciblé lorsqu’une nouvelle variante publique d’erreur ou de module est introduite.

kb-core/USAGE.md

@@ -0,0 +1,108 @@
+<!-- file: kb-core/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de kb-core
+
+## Objectif
+
+La crate expose les contrats minimaux communs utilisés par les autres crates du workspace.
+
+## Résultat partagé
+
+```rust
+fn validate_name(name: &str) -> kb_core::Result<()> {
+    if name.trim().is_empty() {
+        return std::result::Result::Err(kb_core::Error::new(
+            "name_empty",
+            "name must not be empty",
+        ));
+    }
+
+    return std::result::Result::Ok(());
+}
+```
+
+## Erreur personnalisée stable
+
+```rust
+let error = kb_core::Error::new(
+    "profile_missing",
+    "the requested profile does not exist",
+);
+
+assert_eq!(error.code(), "profile_missing");
+assert_eq!(
+    error.message(),
+    "the requested profile does not exist"
+);
+```
+
+`Error::new` doit recevoir un code stable destiné aux logs, aux tests et aux adaptateurs UI.
+
+## Familles d’erreur
+
+```rust
+let config_error = kb_core::Error::config("missing active profile");
+let io_error = kb_core::Error::io("cannot read configuration file");
+let db_error = kb_core::Error::db("database connection refused");
+
+assert_eq!(config_error.code(), "config");
+assert_eq!(io_error.code(), "io");
+assert_eq!(db_error.code(), "db");
+```
+
+Les constructeurs publics disponibles couvrent notamment la configuration, les I/O, JSON, tracing, Tauri, HTTP, WebSocket, base de données, état invalide, absence de connexion et fonctionnalité non implémentée.
+
+## Conversion depuis une erreur I/O
+
+```rust
+let read_result = std::fs::read_to_string("missing.file");
+
+let core_result: kb_core::Result<std::string::String> =
+    match read_result {
+        std::result::Result::Ok(value) => {
+            std::result::Result::Ok(value)
+        },
+        std::result::Result::Err(error) => {
+            std::result::Result::Err(kb_core::Error::from(error))
+        },
+    };
+```
+
+## Identité d’un module
+
+```rust
+let name = kb_core::ModuleName(
+    "spl_token_decoder".to_string(),
+);
+let version = kb_core::ModuleVersion(
+    "0.4.6".to_string(),
+);
+let kind = kb_core::ModuleKind::Decoder;
+
+assert_eq!(name.0, "spl_token_decoder");
+assert_eq!(version.0, "0.4.6");
+assert_eq!(kind, kb_core::ModuleKind::Decoder);
+```
+
+`ModuleKind` distingue actuellement les ingestors, extractors, observers, decoders, materializers, aggregators et validators.
+
+## Erreurs et invariants
+
+- le code d’une erreur doit rester stable ;
+- le message peut être détaillé pour l’opérateur, mais ne doit pas contenir de secret ;
+- `ModuleName` et `ModuleVersion` sont des identités, pas des mécanismes de résolution dynamique ;
+- une nouvelle variante publique doit rester compatible avec les consommateurs du workspace.
+
+## Tests de référence
+
+- `custom_error_preserves_code_and_message` ;
+- `family_error_formats_with_family_prefix`.
+
+Ces tests illustrent le contrat stable entre code, message et représentation textuelle.
+
+## Limites durables
+
+- `kb-core` ne remplace pas les types métier spécialisés ;
+- elle ne fournit pas de journalisation ni de sérialisation automatique des erreurs ;
+- elle ne contient pas de logique de transport, stockage ou protocole.