<!-- file: crates/ksp-logging-lib/README.md -->
<!-- version: 6 -->

# ksp-logging-lib

`ksp-logging-lib` est la façade commune de logging/tracing runtime de Khadhroony Solana Project.

## Responsabilités

La crate possède :

- les cinq niveaux KSP `error`, `warn`, `info`, `debug` et `trace` ;
- les macros d'événements et de spans qui préservent le callsite du consommateur ;
- `LoggingSettings`, la console explicite et les settings fichier indépendants de Config ;
- les formats runtime `Human/Compact/Pretty/Json` ;
- zéro, un ou plusieurs outputs fichier actifs simultanément, identifiés par `output_id` unique ;
- le routing par output sur niveau, target KSP et champ structuré `domain` ;
- l'héritage du `domain` effectif à travers les spans, avec possibilité pour un event ou un span enfant de le remplacer explicitement ;
- l'installation unique du subscriber global ;
- le hot reload via `reinitialize` sans second subscriber global ;
- `LoggingRuntimeIdentity` pour isoler les fichiers persistants par lancement sans muter les `FileSettings` source ;
- l'observabilité des file sinks actifs via `RuntimeFileMetadata`, avec maintien de la même identité à travers les hot reloads ;
- le takeover des logs : les targets externes sont silencieux par défaut ;
- les writers non bloquants console/fichier et leurs `WorkerGuard` ;
- les compteurs agrégés de lignes abandonnées et le compteur cumulatif par `output_id` fichier ;
- la rotation fichier, le stripping ANSI persistant et l'ANSI configurable pour la console ;
- l'instrumentation de scopes synchrones et de `Future` async.

L'API async de production reste indépendante de tout executor. Tokio est utilisé uniquement comme `dev-dependency` afin de valider `instrument(...)` sur un executor réel en mode current-thread et multi-thread ; il ne fait pas partie des dépendances runtime de la crate.

## Routing `domain`

`OutputFilter` applique désormais les trois dimensions :

```text
level
targets[]
domains[]
```

Le `domain` reste un champ structuré distinct du target. Sa résolution runtime suit ces règles :

- le `domain` porté directement par un event est prioritaire ;
- sinon l'event hérite du `domain` effectif de son span ;
- un span qui porte son propre `domain` remplace celui de son parent ;
- un span sans `domain` hérite de celui de son parent au moment de sa création ;
- les événements de lifecycle de span utilisent le `domain` effectif du span concerné ;
- un selector `domains = ["*"]` accepte aussi les événements sans `domain` ;
- un selector nommé correspond par préfixe et ne sélectionne pas un événement sans `domain`.

Le routing `domain` est appliqué en plus du niveau et du target de l'output. Il ne modifie ni le target propriétaire KSP ni les champs formatés.

## Frontières

Une crate KSP comportementale qui journalise son activité dépend de `ksp-logging-lib` et n'utilise pas directement `tracing`, `tracing-subscriber` ou `tracing-appender`.

Les événements utiles issus d'une dépendance externe ne sont pas renommés : la crate KSP propriétaire de l'opération réémet explicitement l'information utile sous son propre target KSP.

`ksp-logging-lib` ne dépend pas de `ksp-config-lib`. Config peut construire un `LoggingSettings` puis une application appelle `initialize`, `initialize_with_identity` et `reinitialize` selon son besoin. L'identité de lancement reste une responsabilité de la couche application : Logging la valide, la conserve dans le `LoggingGuard` et l'applique aux noms de fichiers actifs.

## Documentation

- [`USAGE.md`](USAGE.md) — utilisation concrète de la façade et du runtime ;
- [`TODO.md`](TODO.md) — capacités explicitement différées ou points restant à fermer.