<!-- 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.