Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.1.0-pre.069

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-07-31 13:25:26 +02:00
parent f23ecd6675
commit 46071b7fed
21 changed files with 799 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/README.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Documentation active de Khadhroony Bot3
@@ -81,3 +81,12 @@ CHANGELOG.md
```
Leur création commencera après stabilisation des documents transversaux, par lots de crates. `USAGE.md` documentera les APIs publiques réelles et pourra signaler les tests particulièrement instructifs.
## Documentation des crates
Le premier lot documenté comprend :
- [`kb-lib`](../kb-lib/README.md) ;
- [`kb-store`](../kb-store/README.md) ;
- [`kb-config`](../kb-config/README.md) ;
- [`kb-logging`](../kb-logging/README.md).

82
docs/rules/CRATE_DOCUMENTATION_RULES.md
View File

@@ -16,7 +16,7 @@ USAGE.md
CHANGELOG.md
```
`USAGES.md` et les autres noms concurrents sont interdits. `001.README.md` reste autorisé comme index de répertoire lorsque le tri lexical au début d’un répertoire très fourni est utile, par exemple sous `idls/`; il ne remplace jamais le `README.md` obligatoire à la racine d’une crate.
Les variantes `001.README.md`, `USAGES.md` ou tout autre nom concurrent sont interdites dans la documentation active.
Ces fichiers doivent être écrits pour l’architecture actuelle de `khadhroony-bot3`. Les documents de `olddocs/archivekbot2/` sont des sources historiques : leur contenu peut être étudié, vérifié, réinterprété et adapté, mais ne doit jamais être déplacé, copié automatiquement ou rendu normatif sans réécriture explicite.
@@ -34,7 +34,7 @@ Pour chaque document de crate :
- conserver les détails historiques dans les changelogs et archives, non dans le README ou le guide d’utilisation ;
- mettre à jour le numéro de version documentaire placé dans l’en-tête du fichier lorsqu’un changement substantiel est effectué.
Les sections obligatoires ne doivent pas être laissées vides. Lorsqu’aucun élément n’est recensé, l’indiquer explicitement.
Les documents ne doivent pas contenir de sections vides ni de constats sans action. Une section sans contenu utile est omise.
## 3. `README.md`
@@ -109,12 +109,14 @@ Une réexportation publique doit être vérifiée jusqu’à son chemin d’acc
8. erreurs publiques et conditions d’échec ;
9. exemples réalistes, préférablement compilables ;
10. utilisation des binaires ou commandes, lorsqu’applicable ;
11. limites connues ;
11. contraintes et limites durables de l’API actuelle ;
12. liens vers les tests, exemples, fixtures et matrices canoniques.
Chaque API publique significative doit disposer d’au moins un exemple ou être couverte par un exemple de scénario explicitement identifié. Les APIs triviales ou regroupées peuvent partager un exemple lorsqu’il démontre réellement leur usage.
Les travaux planifiés pour supprimer une limite temporaire appartiennent au TODO et ne sont pas répétés dans `USAGE.md`.
Les tests unitaires peuvent être documentés lorsqu’ils illustrent un contrat public, un invariant, un format canonique ou une régression importante. `USAGE.md` doit alors les référencer et expliquer ce qu’ils démontrent, sans transformer les helpers internes en API publique.
Les exemples Rust doivent respecter les règles du workspace, y compris les conventions de propagation d’erreurs.
Chaque API publique significative doit disposer d’au moins un exemple ou être couverte par un exemple de scénario explicitement identifié. Les APIs triviales ou regroupées peuvent partager un exemple lorsqu’il démontre réellement leur usage.
### 4.4 Crates sans API bibliothèque publique
@@ -124,28 +126,20 @@ Une crate principalement binaire ou interne conserve un `USAGE.md`. Le document
### 5.1 Rôle
Le TODO maintient l’état futur propre à la crate. Il ne sert ni de roadmap général ni de changelog.
Le TODO maintient uniquement les travaux futurs confirmés propres à la crate. Il ne sert ni de roadmap général, ni de changelog, ni de fiche descriptive.
### 5.2 Sections obligatoires
### 5.2 Organisation
Le fichier distingue au minimum :
Le fichier est organisé en tâches et, lorsque nécessaire, en sous-tâches. Les sections sont choisies selon le travail réellement recensé : version cible, fonctionnalité, dette technique, tests, validation réseau, documentation, migration ou dépendance externe.
- fonctionnalités manquantes ;
- dette technique ;
- tests manquants ;
- validations Devnet/Mainnet manquantes ;
- documentation manquante ;
- dépendances ou contraintes externes ;
- éléments confirmés mais reportés ;
- hors périmètre.
Chaque entrée doit :
Chaque entrée doit préciser, lorsque connu :
- commencer par une action à réaliser ;
- être vérifiable et supprimable une fois terminée ;
- préciser sa version cible, sa priorité, sa dépendance ou son critère de clôture lorsque cette information est connue ;
- rester dans le TODO uniquement tant qu’elle n’est pas achevée.
- son statut ;
- sa priorité ou son ordre relatif ;
- sa dépendance ;
- son critère de clôture ;
- la version ou série cible si elle est déjà décidée.
Une contrainte externe ne figure dans le TODO que si elle bloque ou conditionne une tâche explicite. Une absence de validation Devnet/Mainnet n’est mentionnée que lorsqu’une validation réseau doit réellement être exécutée pour cette crate.
### 5.3 Relation avec `docs/IDEA_REMINDERS.md`
@@ -157,38 +151,40 @@ Une idée peut être intégrée au TODO d’une crate uniquement après :
2. identification de la crate réellement responsable ;
3. vérification qu’elle n’est pas déjà implémentée ou remplacée ;
4. reformulation en tâche vérifiable ;
5. classement dans la bonne section et selon un ordre cohérent ;
6. ajout des dépendances et limites connues.
5. classement selon un ordre cohérent ;
6. ajout de ses dépendances ou critères de clôture.
Une idée encore exploratoire reste dans `docs/IDEA_REMINDERS.md` ou dans un document de décision ; elle ne doit pas être présentée comme engagement de crate.
Une idée encore exploratoire reste dans `docs/IDEA_REMINDERS.md` ou dans un document de décision.
### 5.4 Interdictions
Le TODO ne doit pas :
- conserver ou répéter les travaux déjà terminés ;
- conserver une tâche terminée ;
- contenir des phrases telles que « aucune tâche », « aucune validation » ou « hors périmètre » ;
- décrire le comportement actuel de la crate ;
- contenir l’historique des corrections ;
- recopier le ROADMAP général ;
- transformer une hypothèse en obligation ;
- masquer une fonctionnalité partiellement implémentée sous un statut binaire terminé/non terminé.
- transformer une hypothèse en obligation.
## 6. `CHANGELOG.md`
### 6.1 Rôle
Le changelog de crate retrace l’évolution fonctionnelle, structurelle et contractuelle de cette crate.
Le changelog de crate retrace chronologiquement les changements effectivement intégrés à cette crate. Il conserve le détail des releases, prereleases et correctifs `fix` qui l’ont affectée.
Il ne contient ni section `Non publié`, ni tâches futures, ni roadmap, ni liste de limitations sans changement associé.
### 6.2 Base historique minimale
Chaque changelog de crate doit contenir au minimum :
Chaque changelog de crate doit contenir au minimum une section `0.1.0` décrivant :
- une section `Non publié` ;
- une section `0.1.0` décrivant la migration depuis les composants correspondants de `khadhroony-bot2` ;
- la migration depuis les composants correspondants de `khadhroony-bot2` ;
- les consolidations, renommages ou suppressions de frontières de crates intervenues dans bot3 ;
- l’adoption des nouvelles règles Rust et Khadhroony applicables ;
- les validations réellement exécutées et les limitations encore connues.
- les validations réellement exécutées pendant cette version.
La section `0.1.0` synthétise la migration initiale. À partir de cette base, le changelog de crate conserve le détail des prereleases et correctifs `fix` qui ont touché la crate, afin de reprendre durablement les informations pertinentes de chaque `delta.md`.
Les prereleases et correctifs ultérieurs sont ajoutés au moment où leurs changements sont intégrés à la crate.
### 6.3 Catégories
@@ -201,23 +197,19 @@ Utiliser uniquement les catégories pertinentes parmi :
- Migré ;
- Compatibilité ;
- Validation ;
- Limitations connues ;
- Documentation.
Ne pas créer des sections vides.
Ne pas créer de section vide. Une limitation n’est mentionnée que si elle résulte directement du changement décrit dans l’entrée considérée ; les travaux nécessaires à sa suppression appartiennent au TODO.
### 6.4 Versions et corrections
Le changelog de crate distingue clairement :
Le changelog distingue clairement :
- version publiée ;
- prerelease ;
- correctif `fix` ;
- changement non publié.
- versions fonctionnelles ;
- prereleases ;
- correctifs `fix`.
Le changelog général suit une granularité différente : il décrit les changements entre versions fonctionnelles, par exemple de `0.4.6` à `0.4.7`, sans détailler les prereleases ni les correctifs `fix`. Les détails de livraison restent dans les changelogs des crates concernées.
Une modification fonctionnelle de la crate impose une mise à jour de son changelog. Une modification documentaire pure peut être regroupée sous `Non publié / Documentation`.
Une modification fonctionnelle ou documentaire de la crate impose une entrée sous l’identifiant exact de la livraison qui l’intègre. Les informations pertinentes de `delta.md` concernant la crate sont reprises et reformulées dans son changelog.
### 6.5 Provenance bot2
@@ -241,7 +233,7 @@ Les matrices actives maintenues sous :
test-fixtures/contract-matrices/
```
restent les références canoniques. Elles servent à la fois de contrats documentaires et de fixtures exécutées par des tests unitaires ou d’intégration. Elles ne doivent pas être dupliquées dans `docs/`.
restent les références canoniques. Elles ne doivent pas être dupliquées dans `docs/`.
Les documents de crate et de protocole doivent les référencer par lien et expliquer leur rôle, leur portée et leur statut de validation.

14
docs/templates/CRATE_CHANGELOG_TEMPLATE.md vendored
View File

@@ -5,11 +5,11 @@
# Changelog de `<nom-de-crate>`
## Non publié
## `<version-ou-prerelease-fix>`
### Documentation
### Ajouté / Modifié / Corrigé / Supprimé / Validation / Documentation
- Création ou mise à jour de la documentation de crate.
- Décrire uniquement les changements effectivement intégrés par cette livraison.
## 0.1.0
@@ -24,11 +24,3 @@
### Validation
- Indiquer uniquement les validations réellement exécutées et pertinentes pour cette crate.
### Limitations connues
- Indiquer les fonctionnalités partielles, non raccordées ou non validées.
## Historique détaillé des livraisons
Ajouter les prereleases et correctifs `fix` ayant réellement modifié cette crate, en reprenant les informations pertinentes des `delta.md`.

24
docs/templates/CRATE_TODO_TEMPLATE.md vendored
View File

@@ -3,24 +3,12 @@
# Modèle de TODO de crate
# Travaux restant pour `<nom-de-crate>`
# TODO — `<nom-de-crate>`
## Fonctionnalités manquantes
## `<version, fonctionnalité ou lot>`
## Dette technique
- [ ] action vérifiable à réaliser ;
- [ ] sous-tâche ordonnée si nécessaire ;
- [ ] validation ou documentation à produire pour clôturer le lot.
## Tests manquants
## Validations Devnet/Mainnet manquantes
## Documentation manquante
## Dépendances ou contraintes externes
## Éléments confirmés mais reportés
## Hors périmètre
> Ne reprendre une idée de `docs/IDEA_REMINDERS.md` qu’après confirmation, attribution à cette crate et reformulation en tâche vérifiable.
> Supprimer toute tâche dès que sa réalisation est confirmée et la reporter dans le changelog de la crate.
> Supprimer chaque tâche terminée. Ne conserver ni section vide, ni constat sans action. Ne reprendre une idée de `docs/IDEA_REMINDERS.md` qu’après confirmation, attribution à cette crate et reformulation en tâche vérifiable.

8
docs/templates/CRATE_USAGE_TEMPLATE.md vendored
View File

@@ -39,12 +39,10 @@ Pour chaque API ou groupe cohérent :
Supprimer cette section si aucun binaire public n’existe.
## Tests de référence
Documenter les tests unitaires particulièrement instructifs qui démontrent un contrat public, un invariant, un format canonique ou une non-régression.
## Limites connues
## Contraintes et limites durables
## Références
Lier les tests, exemples, fixtures et matrices canoniques sans les dupliquer.
> Ne pas répéter ici une limite temporaire déjà planifiée dans `TODO.md`. Les exemples Rust doivent respecter les règles du workspace.

42
kb-config/CHANGELOG.md Normal file
View File

@@ -0,0 +1,42 @@
<!-- file: kb-config/CHANGELOG.md -->
<!-- version: 2 -->
# CHANGELOG — kb-config
## 0.1.0-pre.069-fix-001
### Corrigé
- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
- retrait des limitations et travaux futurs, désormais maintenus dans `TODO.md` ou `USAGE.md` selon leur nature ;
- clarification de la séparation entre historique de prerelease et objectifs futurs.
### Documentation
- réécriture de `TODO.md` sous forme de tâches uniquement ;
- correction des exemples de `USAGE.md` afin de ne pas utiliser l’opérateur `?`.
## 0.1.0-pre.069
### Documentation
- création de `TODO.md`, `USAGE.md` et du changelog détaillé ;
- réécriture du README selon l’architecture bot3.
## 0.1.0
### Migré
- migration et consolidation de la configuration typée bot2 dans `kb-config` ;
- conservation du schéma JSON, des profils, endpoints, listeners, paramètres de stockage, logging, wallet et exécution.
### Modifié
- adoption des règles Rust 2024 et Khadhroony ;
- export TypeScript contrôlé des types destinés au frontend ;
- validation structurée par `kb_core::Error`.
### Validation
- validation de l’exemple contre le schéma ;
- tests de round-trip, profils actifs, placeholders, URLs, rôles et invariants opérationnels.

99
kb-config/README.md
View File

@@ -1,90 +1,41 @@
<!-- file: kb-config/README.md -->
<!-- version: 7 -->
<!-- version: 4 -->
# kb-config
Ce crate définit le contrat de configuration commun du workspace.
`kb-config` définit le contrat de configuration typé du workspace, son schéma JSON embarqué et les fonctions de chargement, résolution d’environnement, validation et sérialisation.
## Rôle dans l'écosystème
## Responsabilités
`kb-config` charge, valide et sérialise un fichier JSON contenant plusieurs profils. Un seul profil est actif à l'exécution grâce au champ `active_profile`.
- exposer `AppConfig` et les sections de configuration publiques ;
- valider le JSON contre le schéma embarqué ;
- appliquer les invariants métier après désérialisation ;
- charger `.env` et `.env.local` depuis la racine du workspace ;
- résoudre les placeholders `${NAME}` et `${NAME:-fallback}` ;
- sélectionner le profil actif ;
- exporter les types nécessaires au frontend avec `ts-rs`.
Le crate fournit les structures typées runtime pour :
## Hors périmètre
- l'application et l'environnement ;
- les sorties de logs console, fichier humain, fichier JSON et fichier erreurs ;
- les filtres de targets `tracing` ;
- les stores PostgreSQL et SQLite ;
- les endpoints HTTP JSON-RPC et WebSocket Solana ;
- les rôles et limites par endpoint ;
- les listeners Solana standards ;
- le wallet temporaire géré par profil ;
- les permissions d'envoi localnet/devnet/testnet/mainnet ;
- les plafonds de dépense, frais, priorité et fraîcheur du blockhash ;
- les pages de démonstration Tauri.
La crate n’initialise ni le logging, ni PostgreSQL, ni les transports et ne manipule aucun secret de wallet. Elle fournit uniquement la configuration validée à ces consommateurs.
## Wallet temporaire
## Surface publique
Le profil `local_devnet` active un wallet persistant de laboratoire sous :
Les principales fonctions sont `read_config_json_file_with_environment`, `parse_config_json`, `validate_config`, `validate_config_json_schema`, `active_profile` et les sérialiseurs JSON. Les types publics couvrent les profils, endpoints, listeners, logging, base de données, wallet, exécution et démonstration.
```text
wallets/temporary/local_devnet/local-devnet-operator.json
```
## Relations
Les profils mainnet conservent `temporary_wallet_enabled = false`. La validation typée refuse un wallet temporaire actif sur `mainnet-beta`, une persistance sans activation et les alias pouvant produire un chemin arbitraire.
- dépend de `kb-core` pour les erreurs structurées ;
- alimente `kb-logging`, `kb-store`, `kb-onchain-transport`, `kb-pipeline`, `kb-wallet` et les applications ;
- utilise [`../config/example.config.json`](../config/example.config.json) et [`../config/schema.config.json`](../config/schema.config.json) comme exemple utilisateur et contrat de schéma actifs.
## Exécution
## Statut
La configuration sépare :
La configuration actuelle est fonctionnelle et validée. Un futur découpage de la configuration générale et du logging est prévu en `0.5.x` afin de réduire les duplications entre profils.
- le dry-run par défaut ;
- l'obligation de simulation ;
- la confirmation opérateur ;
- les plafonds de dépense localnet, devnet, testnet et mainnet ;
- le plafond de frais ;
- le plafond de prix par compute unit ;
- l'âge maximal du recent blockhash.
## Documents
Un cluster dont l'envoi est activé doit disposer d'un plafond de dépense positif. Toute dépense configurée exige la simulation et toute dépense mainnet exige la confirmation opérateur. Les paramètres de confirmation sont bornés et le plafond d’airdrop Devnet est interdit dans les profils d’un autre cluster.
## Validation
La validation se fait en deux étapes :
1. validation JSON brute via `config/schema.config.json` et `jsonschema` ;
2. validation typée après désérialisation Rust.
## Secrets et placeholders
Le fichier versionné doit rester sans secret. Les placeholders restent directement dans les URLs. Les keypairs générés par `kb-wallet` vivent hors du fichier de configuration et sous un répertoire ignoré par Git.
## Exports TS-rs
Les structures exposées à Tauri utilisent `TS` avec un chemin `export_to` explicite. Les fichiers générés servent uniquement au partage des types Rust/TypeScript et ne remplacent pas le schéma JSON runtime.
```bash
cargo test export_bindings -p kb-config
cargo test -p kb-config settings::tests::
```
## Résolution de l'environnement
`kb-config` est l'unique propriétaire du chargement des fichiers `.env` utilisés par la configuration. La priorité est déterministe :
1. variables déjà présentes dans l'environnement du processus ;
2. fichier indiqué par `KB_ENV_FILE`, sinon `.env` à la racine du workspace ;
3. fallback `${NOM:-valeur}` déclaré dans le JSON ;
4. conservation de `${NOM}` lorsqu'une valeur requise reste absente, afin que les consommateurs optionnels puissent échouer seulement à l'utilisation.
Les crates métier ne chargent pas elles-mêmes de fichier `.env`.
Le modèle racine utilise :
```text
HELIUS_API_KEY
KB_POSTGRES_MAINNET_URL
KB_POSTGRES_DEVNET_URL
KB_POSTGRES_TEST_URL
```
Les deux URLs runtime alimentent les profils correspondants. `KB_POSTGRES_TEST_URL` reste réservé aux tests d’intégration de `kb-store`.
- [Utilisation](USAGE.md)
- [Travaux restants](TODO.md)
- [Historique](CHANGELOG.md)
- [Architecture](../docs/architecture/ARCHITECTURE.md)

15
kb-config/TODO.md Normal file
View File

@@ -0,0 +1,15 @@
<!-- file: kb-config/TODO.md -->
<!-- version: 2 -->
# TODO — kb-config
## Série 0.5.x — scission de la configuration
- [ ] définir si la configuration doit être scindée en deux ou trois fichiers ;
- [ ] extraire les blocs de logging dupliqués entre profils vers une configuration dédiée ;
- [ ] alléger la configuration générale sans casser les invariants existants ;
- [ ] définir une stratégie de migration explicite pour les fichiers de configuration actuels ;
- [ ] maintenir l’identité entre le schéma embarqué et `config/schema.config.json` ;
- [ ] ajouter les tests de migration et de compatibilité du futur format multi-fichiers ;
- [ ] mettre à jour la documentation et les exemples après implémentation ;
- [ ] coordonner la migration avec `kb-logging` et toutes les crates consommatrices.

100
kb-config/USAGE.md Normal file
View File

@@ -0,0 +1,100 @@
<!-- file: kb-config/USAGE.md -->
<!-- version: 2 -->
# Utilisation de kb-config
## Chargement recommandé
```rust
let config_result = kb_config::read_config_json_file_with_environment(
std::path::Path::new("config/example.config.json"),
std::path::Path::new("."),
);
let config = match config_result {
Ok(value) => value,
Err(error) => return Err(error),
};
let profile = match kb_config::active_profile(&config) {
Ok(value) => value,
Err(error) => return Err(error),
};
```
Cette fonction charge l’environnement du workspace, résout les placeholders puis applique successivement le schéma JSON, la désérialisation typée et les invariants métier.
## Chargement de l’environnement
```rust
let report = match kb_config::load_workspace_environment(std::path::Path::new(".")) {
Ok(value) => value,
Err(error) => return Err(error),
};
```
`EnvironmentLoadReport` indique les fichiers chargés. Les placeholders non résolus sans fallback restent visibles afin que la validation ou le consommateur puisse les signaler explicitement.
## Validation et parsing
```rust
if let Err(error) = kb_config::validate_config_json_schema(raw_json) {
return Err(error);
}
let config = match kb_config::parse_config_json(raw_json) {
Ok(value) => value,
Err(error) => return Err(error),
};
if let Err(error) = kb_config::validate_config(&config) {
return Err(error);
}
```
`parse_config_json` effectue déjà les deux validations ; les appels séparés servent aux outils de diagnostic.
## Sérialisation
```rust
let compact = match kb_config::serialize_config_json(&config) {
Ok(value) => value,
Err(error) => return Err(error),
};
let pretty = match kb_config::serialize_config_json_pretty(&config) {
Ok(value) => value,
Err(error) => return Err(error),
};
```
La configuration est validée avant sérialisation.
## Schéma embarqué
```rust
let schema_text = kb_config::config_json_schema_text();
let schema_value = match kb_config::config_json_schema_value() {
Ok(value) => value,
Err(error) => return Err(error),
};
```
Le schéma actif est aussi disponible sous [`../config/schema.config.json`](../config/schema.config.json). Le fichier [`../config/example.config.json`](../config/example.config.json) fournit un exemple utilisateur complet.
## Types publics importants
- `AppConfig`, `ProfileConfig`, `AppSectionConfig` ;
- `DatabaseConfig`, `PostgresConfig`, `SqliteConfig`, `DataConfig` ;
- `SolanaConfig`, `HttpEndpointConfig`, `WsEndpointConfig`, `EndpointRoleConfig` ;
- `ListenerConfig` et ses variantes ;
- `LoggingConfig`, `LogTargetConfig`, `LogTargetFilterConfig` ;
- `WalletConfig`, `ExecutionConfig`, `DemoConfig`.
## Erreurs et invariants
Les erreurs utilisent `kb_core::Error` avec un code stable. Les validations couvrent notamment l’unicité des profils, l’existence du profil actif, les URLs, les rôles d’endpoints, les limites d’exécution, les routes de logging et les contraintes wallet.
## Tests instructifs
Les tests `example_config_validates_against_schema`, `example_config_parses_and_resolves_active_profile` et `example_config_routes_global_and_operational_crate_files` démontrent le contrat complet de l’exemple actif. Les tests `parser_rejects_*` et `schema_rejects_*` documentent les invariants refusés.
## Limites
- format JSON uniquement ;
- la crate valide les références et paramètres, mais n’ouvre aucune connexion externe.

42
kb-lib/CHANGELOG.md Normal file
View File

@@ -0,0 +1,42 @@
<!-- file: kb-lib/CHANGELOG.md -->
<!-- version: 2 -->
# CHANGELOG — kb-lib
## 0.1.0-pre.069-fix-001
### Corrigé
- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
- retrait des limitations et travaux futurs du changelog ;
- correction de la frontière entre historique, TODO et limites durables d’utilisation.
### Documentation
- réécriture de `TODO.md` sous forme de tâches uniquement ;
- correction des exemples de `USAGE.md` afin de ne pas utiliser l’opérateur `?`.
## 0.1.0-pre.069
### Documentation
- ajout de `README.md`, `TODO.md`, `USAGE.md` et du présent changelog selon les normes bot3.
## 0.1.0
### Migré
- consolidation des modèles, décodeurs, exécuteurs et matérialisateurs issus de nombreuses crates bot2 dans une façade unique ;
- migration des surfaces Solana Core, SPL Memo, SPL Token, SPL ATA, Token-2022, registre ElGamal et du décodeur Metaplex Token Metadata ;
- migration des contrats de replay, de sécurité et de matérialisation.
### Modifié
- adoption de Rust 2024, de `#![forbid(unsafe_code)]`, `#![deny(unreachable_pub)]` et des conventions strictes d’exports, d’erreurs et de tracing ;
- remplacement des anciennes frontières de crates par des modules privés et des réexports publics contrôlés.
### Validation
- tests unitaires des décodeurs, exécuteurs, matérialisateurs et contrats consolidés ;
- matrices contractuelles chargées par les tests concernés ;
- validations Devnet conservées pour les scénarios explicitement couverts pendant la migration.

168
kb-lib/README.md
View File

@@ -1,148 +1,68 @@
<!-- file: kb-lib/README.md -->
<!-- version: 13 -->
<!-- version: 14 -->
# kb-lib
`kb-lib` regroupe les modèles partagés et les composants de décodage, matérialisation et exécution de `khadhroony-bot3`. Les composants restent séparés par modules privés et sont exposés par la façade unique `kb-lib/src/lib.rs`.
`kb-lib` est la bibliothèque fonctionnelle consolidée de `khadhroony-bot3`. Elle expose les modèles partagés, les contrats et implémentations de décodage, de matérialisation, d’exécution et de sécurité nécessaires au pipeline Solana.
## Décodeur Solana Core
## Périmètre
`DcSolanaCoreDecoder` est le premier décodeur concret porté depuis bot2. Il implémente `DcApiInstructionDecoder` et `DcApiProtocolDecoder` sans dépendre de PostgreSQL, du RPC, de Tauri ou du wallet.
La crate regroupe quatre familles internes, exposées par la façade `kb_lib` :
Il couvre les 18 surfaces natives suivantes :
- décodeurs et contrats de décodage contextualisé ;
- exécuteurs, plans préparés et politiques de sécurité ;
- matérialisateurs et projections structurées ;
- modèles canoniques utilisés par les autres crates.
- System Program ;
- Compute Budget ;
- Address Lookup Table ;
- Config et Feature Gate ;
- Vote et Stake ;
- loaders natifs, BPF historiques, upgradeable et Loader v4 ;
- précompiles Ed25519, secp256k1 et secp256r1 ;
- Slashing ;
- ZK ElGamal Proof et l’ancien ZK Token Proof.
Elle couvre actuellement Solana Core, SPL Memo, SPL Token classique, SPL Associated Token Account, Token-2022, le registre SPL ElGamal et le décodeur Metaplex Token Metadata. De nombreux décodeurs et exécuteurs réservés exposent seulement une identité et une compatibilité conservatrice ; ils ne constituent pas une implémentation fonctionnelle.
La matrice `docs/NATIVE_SOLANA_DECODER_MATRIX.json` reste la source machine-readable de la couverture. Les instructions inconnues, tronquées, historiques ou issues d’une transaction échouée conservent les statuts et diagnostics explicites définis par les contrats communs.
## Responsabilités
## Décodeur SPL Memo
- reconnaître et décoder une instruction à partir d’un contexte canonique ;
- publier des déclarations de couverture déterministes ;
- produire des observations et diagnostics typés ;
- construire des plans d’exécution bornés et vérifiables ;
- appliquer les politiques de sécurité avant simulation, signature ou envoi ;
- matérialiser les observations commitées selon des contrats explicites ;
- conserver des modèles indépendants du stockage, du transport et de l’interface desktop.
`DcSplMemoDecoder` couvre exactement les générations v1, v3 et v4. Le payload est lu comme un message brut sans discriminator, borné à 4 096 octets, puis projeté avec son texte UTF-8 complet, sa longueur, son SHA-256, les comptes ordonnés et le statut de commit.
## Hors périmètre
Memo v1 ignore les comptes lors de la validation runtime. Memo v3 et v4 exigent que chaque compte fourni soit signer. Les transactions échouées restent des intentions non commitées et les payloads UTF-8 invalides ou signatures manquantes deviennent des tentatives invalides explicites. La matrice normative est `docs/SPL_MEMO_MATRIX.json`.
`kb-lib` ne persiste aucune donnée, ne dialogue pas directement avec un RPC, ne sélectionne pas un endpoint et ne gère pas les secrets de wallet. Ces responsabilités appartiennent respectivement à `kb-store`, `kb-onchain-transport`, `kb-pipeline` et `kb-wallet`.
## Décodeur SPL Token classique
## Surface publique principale
`DcSplTokenDecoder` couvre exclusivement le Program ID classique
`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`. Il publie 28 déclarations de couverture pour
les tags `0..24`, `38`, `45` et `255`, y compris les variantes historiques, checked,
`WithdrawExcessLamports`, `UnwrapLamports` et `Batch`.
La façade publique est organisée autour de :
Le parseur conserve les montants bruts sans perte, les comptes dans leur ordre d’origine, les
formes d’autorité simple ou multisig, les suffixes runtime et les chemins outer/inner. Une
transaction échouée reste une intention non commitée. `Batch` est borné à 64 enfants, 512 comptes
cumulés et interdit les batches imbriqués. Le décodeur n’invente ni mint, ni decimals, ni état
final ; les validations `M/N`, soldes et autorités existantes restent stateful. La matrice
normative est `docs/SPL_TOKEN_MATRIX.json`.
- `DcApiInstructionDecoder`, `DcApiProtocolDecoder` et les types `DcApi*` ;
- les décodeurs concrets `DcSolanaCoreDecoder`, `DcSplMemoDecoder`, `DcSplTokenDecoder`, `DcSplAssociatedTokenAccountDecoder`, `DcSplToken2022Decoder`, `DcSplElgamalRegistryDecoder` et `DcMetadataMetaplexTokenMetadataDecoder` ;
- `ExApiTypedInstructionExecutor`, `ExApiInstructionExecutor`, les politiques `ExApi*` et les exécuteurs concrets `Ex*Executor` ;
- `ExSafetyChecker` et les décisions de sécurité associées ;
- `MtApiEventMaterializer`, les types `MtApi*` et les matérialisateurs concrets ;
- `MdCoreInstructionReplayInput` et les modèles canoniques réexportés.
## Décodeur SPL Associated Token Account
Le catalogue détaillé et les exemples se trouvent dans [USAGE.md](USAGE.md).
`DcSplAssociatedTokenAccountDecoder` couvre exclusivement
`ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL`. Il reconnaît les trois variantes publiées
`Create`, `CreateIdempotent` et `RecoverNested`, ainsi que l’encodage historique vide de `Create`.
## Matrices contractuelles
Le décodeur conserve les comptes dans leur ordre original, leurs flags, doublons, chemins
outer/inner et le statut de transaction. Il dérive les PDA avec l’ordre canonique
`[wallet, token_program, mint]`, conserve simultanément l’adresse observée et l’adresse attendue,
puis expose tout écart comme diagnostic. SPL Token classique et Token‑2022 sont distingués par leur
Program ID sans reconstruire leur état ni interpréter leurs extensions. La matrice normative est
`docs/SPL_ASSOCIATED_TOKEN_ACCOUNT_MATRIX.json`.
Les matrices actives sont maintenues sous [`../test-fixtures/contract-matrices/`](../test-fixtures/contract-matrices/). Elles servent à la fois de références documentaires et de fixtures exécutées par des tests. Elles ne sont pas dupliquées dans la documentation de la crate.
## Décodeur SPL Token‑2022
## Relations
`DcSplToken2022Decoder` couvre exclusivement
`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`. Il conserve les 48 enveloppes de premier niveau,
les sous-instructions d’extensions dont le wire est officiellement identifiable, les interfaces
Token Metadata et Token Group exécutées directement par Token‑2022, ainsi que `Batch` sans batch
imbriqué.
- dépend de `kb-core` pour le contrat d’erreur commun ;
- dépend de `kb-program-ids` pour le registre canonique des programmes ;
- est consommée par `kb-pipeline`, `kb-store`, `kb-onchain-transport`, `kb-pipeline-demo-scenarios` et `kb-app-demo-desktop` ;
- ne dépend jamais de `kb-store` ni d’une application.
Le décodeur borne les payloads, les chaînes de metadata, le nombre d’enfants et les comptes
cumulés. Les comptes, autorités, offsets de preuve, suffixes et chemins outer/inner restent
ordonnés et exacts. Une transaction échouée produit une intention non commitée. Le parseur public
`decoder_spl_token_2022_parse_token_2022_state()` distingue Mint, Account et Multisig, conserve la base exacte et expose
les entrées TLV ordonnées sans inventer l’état d’un programme externe pointé. La matrice normative
est `docs/SPL_TOKEN_2022_MATRIX.json`.
## Statut et limites
## Décodeur du registre ElGamal
La migration des surfaces historiques jusqu’à un périmètre proche de bot2 `0.4.6` est largement réalisée. Le décodeur et les matérialisations Metaplex Token Metadata sont présents, mais l’exécuteur et la clôture fonctionnelle de cette surface restent à réaliser. Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.
`DcSplElgamalRegistryDecoder` couvre le programme indépendant
`regVYJW7tcT8zipN5YiBvHsvR5jXW1uLFxaHSbugABg`. Il décode exactement `CreateRegistry` et
`UpdateRegistry`, conserve l’offset relatif de preuve et ne prétend jamais vérifier la preuve ZK.
`decoder_spl_elgamal_registry_parse_elgamal_registry_state()` exige exactement 64 octets et restitue le wallet propriétaire, la
clé publique ElGamal et le wire complet. La matrice normative est
`docs/SPL_ELGAMAL_REGISTRY_MATRIX.json`.
## Documents
## Décodeur Metaplex Token Metadata
`DcMetadataMetaplexTokenMetadataDecoder` couvre exclusivement
`metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s`. Il inventorie exactement les 58
discriminateurs `0..=57`, conserve les arguments Borsh, les comptes positionnels,
les placeholders optionnels, les chemins outer/CPI et les transactions échouées
comme intentions non commitées.
La façade `kb_lib` expose aussi les parseurs bornés des 15 variantes
`Key 0..=14` : Metadata, Edition et Master Edition,
Edition Marker V1/V2, Token Record, records de délégation et d’autorité, Token
Owned Escrow et Reservation List historiques. Chaque parseur vérifie l’owner,
le PDA, le bump, la longueur et les suffixes avant projection. Les comptes
historiques gardent une provenance et un lifecycle matérialisables, mais une
politique d’exécution définitivement interdite. La matrice normative est
`docs/METAPLEX_TOKEN_METADATA_MATRIX.json`.
## API publique utile
- `MtApiEventMaterializer`, `MtApiMaterializerIdentity`, `MtApiMaterializationTransactionPolicy`, `MtApiMaterializerExecutionResult` et `MtApiMaterializedOutput` : contrat complet utilisable par un matérialiseur interne ou externe ;
- `MtLifecycleMaterializer`, `MtAdminMaterializer`, `MtComplianceAuditMaterializer` et `MtStakingMaterializer` : matérialisateurs Solana natifs concrets ;
- `materializer_admin_materialize_token_2022_state_snapshots()` et `materializer_admin_materialize_elgamal_registry_state_snapshot()` : projections stateful d’administration déjà exposées ;
- `DcSolanaCoreDecoder` : décodeur concret natif ;
- `DcSplMemoDecoder` : décodeur exact des trois générations SPL Memo ;
- `DcSplTokenDecoder` : décodeur exact du programme SPL Token classique ;
- `DcSplAssociatedTokenAccountDecoder` : décodeur exact du programme Associated Token Account ;
- `DcSplToken2022Decoder` : décodeur exact des instructions Token‑2022 ;
- `DcToken2022State`, `DcToken2022StateKind`, `DcToken2022TlvEntry` et `decoder_spl_token_2022_token_2022_state()` : API publique de lecture d’état Token‑2022 ;
- `DcSplElgamalRegistryDecoder`, `DcSplElGamalRegistryState` et `decoder_spl_elgamal_registry_parse_elgamal_registry_state()` : API publique du registre ElGamal ;
- `DcMetadataMetaplexTokenMetadataDecoder` : décodeur exact du programme Metaplex Token Metadata ;
- les fonctions `decoder_metadata_metaplex_token_metadata_*` et les types `DcMetadataMtm*` : parseurs et snapshots publics des comptes Metaplex ;
- les 98 types réservés `Dc*Decoder` : squelettes compatibles avec `DcApiProtocolDecoder`, exposant 97 Program IDs enregistrés et la frontière générique Anchor sans Program ID ;
- `DcApiInstructionDecoder` : contrat de reconnaissance, couverture et décodage contextualisé ;
- `DcApiProtocolDecoder` : contrat de compatibilité avec les observations historiques ;
- `ExSolanaCoreExecutor`, `ExSolanaCoreExecutionIntent` et `ExSolanaCoreOperation` : exécuteur natif fonctionnel et contrat typé couvrant 109 opérations ;
- les constantes `EX_SOLANA_CORE_*_OPERATION` : codes stables des opérations System, Compute Budget, ALT, précompiles, Config, Feature, Slashing, ZK ElGamal, Stake, Vote et Loaders ;
- `ExSafetyChecker`, `ExSafetyDecision`, `ExSafetyEvaluation` et `ExSafetyViolation` : garde-fous communs avant simulation, signature et envoi ;
- `ExSplMemoExecutor`, `ExSplMemoExecutionIntent` et `ExSplMemoOperation` : exécuteur SPL Memo v4 fonctionnel, avec v1/v3 explicitement decode-only ;
- `ExApiTypedInstructionExecutor` et `ExApiInstructionExecutor` : contrat typé actuel et pont JSON historique de l’exécution ;
- `MdCoreInstructionReplayInput` : input source-neutral produit par l’extraction core ;
- `DcApiDecoderExecutionResult`, `DcApiDecoderRecognition` et `DcApiDecoderCoverageDeclaration` : résultats typés du pipeline ;
- modèles canoniques et nomenclature réexportés depuis la façade.
Les helpers, constantes wire et types intermédiaires de chaque composant restent internes. Leurs noms sont préfixés au niveau de la façade interne afin d’éviter les collisions lors de la fusion des anciens crates.
## Exemple
```rust
let decoder = kb_lib::DcSolanaCoreDecoder;
let recognition = kb_lib::DcApiInstructionDecoder::recognize(&decoder, &input);
```
L’appel de décodage complet utilise `DcApiInstructionDecoder::decode` après une reconnaissance compatible. Le pipeline demeure responsable de la sélection du décodeur et de la persistance du résultat.
## Frontières
- `kb-lib` ne dépend jamais de `kb-store`.
- Les décodeurs ne lisent pas un état RPC courant pour reconstruire une transaction historique.
- Une transaction échouée peut produire une intention structurée, jamais une mutation commitée.
- Un matérialiseur externe dépend uniquement des contrats et modèles publics de `kb-lib`, jamais d’un décodeur concret.
- Les squelettes réservés répondent uniquement `Maybe` pour leur Program ID et retournent une liste vide ; ils ne prétendent pas décoder une surface avant son port fonctionnel.
- Les 102 squelettes d’exécuteurs encore réservés annoncent uniquement `Maybe` pour leurs Program IDs enregistrés et construisent un plan réservé à zéro instruction.
- `ExSolanaCoreExecutor` annonce uniquement des capacités exactes `Supported` ou `Unsupported` et ne signe, n’envoie ni ne simule aucune transaction.
- `ExSafetyChecker` évalue les plans et résultats de simulation sans effectuer lui-même d’appel RPC, de signature ou d’envoi.
- `ExSplMemoExecutor` construit uniquement des plans ; il ne signe, n’envoie ni ne simule aucune transaction.
- Les exécuteurs fonctionnels sont portés dans des tranches séparées, sans dépendre des décodeurs.
- [Utilisation](USAGE.md)
- [Travaux restants](TODO.md)
- [Historique de la crate](CHANGELOG.md)
- [Architecture générale](../docs/architecture/ARCHITECTURE.md)
- [Pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md)
- [Matrice des surfaces](../docs/architecture/SURFACE_CRATE_MATRIX.md)

28
kb-lib/TODO.md Normal file
View File

@@ -0,0 +1,28 @@
<!-- file: kb-lib/TODO.md -->
<!-- version: 2 -->
# TODO — kb-lib
## Version 0.4.7 — Metaplex Token Metadata
- [ ] vérifier la couverture exacte des matérialisations Metaplex Token Metadata migrées depuis bot2 ;
- [ ] compléter uniquement les projections Metaplex réellement manquantes ;
- [ ] implémenter l’exécuteur Metaplex Token Metadata à partir des contrats officiels vérifiés ;
- [ ] ajouter les tests unitaires et contractuels de l’exécuteur ;
- [ ] préparer les contrats nécessaires à l’intégration pipeline et aux démonstrations ;
- [ ] valider le parcours d’exécution complet sur un réseau approprié lorsque les prérequis sont réunis.
## Registre SPL ElGamal
- [ ] confirmer si le registre est déployé et utilisable sur Devnet ou Mainnet ;
- [ ] préparer une fixture de preuve `PubkeyValidity` et un compte `Proof Context State` valide si un réseau exploitable est confirmé ;
- [ ] exécuter et documenter une validation réseau réelle avant de déclarer cette surface validée.
## Surfaces ultérieures
- [ ] remplacer les décodeurs et exécuteurs réservés par des implémentations bornées selon le ROADMAP ;
- [ ] maintenir une façade publique lisible lors de chaque ajout de famille ;
- [ ] vérifier que chaque type réservé reste explicitement non fonctionnel tant que sa surface n’est pas implémentée ;
- [ ] documenter chaque nouvelle famille publique lors de son activation ;
- [ ] maintenir les liens vers les matrices canoniques sans les dupliquer ;
- [ ] implémenter l’infrastructure générique des conventions Anchor dans la série `0.6.x`.

120
kb-lib/USAGE.md Normal file
View File

@@ -0,0 +1,120 @@
<!-- file: kb-lib/USAGE.md -->
<!-- version: 2 -->
# Utilisation de kb-lib
## Objectif
Ce guide présente les familles d’API publiques significatives de `kb-lib`. Les helpers privés, éléments `pub(crate)` et modules non réexportés ne font pas partie du contrat consommateur.
## Dépendance
```toml
[dependencies]
kb-lib = { path = "../kb-lib" }
```
Toutes les fonctions retournant `kb_core::Result<T>` utilisent le contrat d’erreur structuré du workspace.
## Décodage contextualisé
`DcApiInstructionDecoder` définit la reconnaissance et le décodage d’une instruction contextualisée. Les décodeurs concrets sont des valeurs sans état.
```rust
use kb_lib::{DcApiInstructionDecoder, DcSolanaCoreDecoder};
let decoder = DcSolanaCoreDecoder;
let recognition = DcApiInstructionDecoder::recognize(&decoder, &input);
let result = DcApiInstructionDecoder::decode(&decoder, &input);
```
Le consommateur doit vérifier le résultat typé et ses diagnostics. Une transaction échouée peut produire une intention structurée, mais pas une mutation committée.
Décodeurs fonctionnels principaux :
- `DcSolanaCoreDecoder` ;
- `DcSplMemoDecoder` ;
- `DcSplTokenDecoder` ;
- `DcSplAssociatedTokenAccountDecoder` ;
- `DcSplToken2022Decoder` ;
- `DcSplElgamalRegistryDecoder` ;
- `DcMetadataMetaplexTokenMetadataDecoder`.
Les types réservés `Dc*Decoder` ne doivent pas être interprétés comme des décodeurs complets : ils publient une compatibilité conservatrice et aucune observation fonctionnelle.
## Lecture d’états Token-2022 et ElGamal
```rust
let state = kb_lib::decoder_spl_token_2022_parse_token_2022_state(
&program_id,
&account_data,
);
let registry = kb_lib::decoder_spl_elgamal_registry_parse_elgamal_registry_state(
&account_data,
);
```
Les parseurs vérifient les bornes et formats qu’ils annoncent. Ils ne reconstruisent pas un état historique depuis un RPC courant.
## Comptes Metaplex Token Metadata
Les fonctions `decoder_metadata_metaplex_token_metadata_decode_*_account` décodent les familles de comptes publiques prises en charge. Le consommateur doit fournir les données et le contexte attendus par la signature exacte de la fonction concernée. Les parseurs conservent les variantes historiques et refusent les longueurs, propriétaires ou suffixes incompatibles.
## Exécution typée
`ExApiTypedInstructionExecutor` produit un `ExApiPreparedExecutionPlan` à partir d’une intention et d’une politique explicites. Les exécuteurs concrets incluent notamment :
- `ExSolanaCoreExecutor` ;
- `ExSplMemoExecutor` pour Memo v4 ;
- `ExSplTokenExecutor` ;
- `ExSplAssociatedTokenAccountExecutor` ;
- `ExSplToken2022Executor` ;
- `ExSplElgamalRegistryExecutor`.
```rust
use kb_lib::{ExApiTypedInstructionExecutor, ExSplMemoExecutor};
let executor = ExSplMemoExecutor;
let plan = ExApiTypedInstructionExecutor::build_prepared_plan(
&executor,
&intent,
&policy,
);
```
Le plan ne signe et n’envoie rien. La simulation, la confirmation opérateur, la soumission et la confirmation réseau appartiennent aux couches d’orchestration et de transport.
Memo v1 et v3 restent non exécutables. Memo v4 est la seule génération exécutable.
## Sécurité
Les types `ExSafetyChecker`, `ExSafetyDecision`, `ExSafetyEvaluation` et `ExSafetyViolation` permettent d’évaluer un plan avant son utilisation. Une décision conservatrice doit être respectée par le consommateur ; elle ne doit pas être contournée par l’application.
## Matérialisation
`MtApiEventMaterializer` définit le contrat public de matérialisation. Les résultats `MtApiMaterializerExecutionResult` contiennent les sorties et diagnostics sans dépendre d’un backend de stockage.
Les fonctions stateful publiques comprennent notamment :
- `materializer_admin_materialize_token_2022_state_snapshots` ;
- `materializer_admin_materialize_elgamal_registry_state_snapshot` ;
- `materializer_token_materialize_token_2022_state_snapshot` ;
- `materializer_metadata_materialize_token_2022_snapshot` ;
- `materializer_metadata_materialize_metaplex_metadata_snapshot` ;
- `materializer_metadata_materialize_metaplex_account_snapshot`.
## Contrat de replay
`MdCoreInstructionReplayInput` représente une instruction extraite avec son contexte transactionnel. Il constitue la frontière entre l’extraction Core, le pipeline de replay et les décodeurs.
## Tests et matrices utiles
Les tests unitaires du décodeur Metaplex et du décodeur Solana Core chargent directement certaines matrices de [`../test-fixtures/contract-matrices/`](../test-fixtures/contract-matrices/). Ils vérifient notamment l’égalité entre les entrées compilées et les contrats JSON, les discriminants, les bornes et les comportements historiques.
Les tests des exécuteurs comparent les instructions produites aux builders officiels et vérifient signers, comptes ordonnés, coûts et politiques de sécurité.
## Limites
- aucune persistance ni acquisition réseau ;
- aucun chargement dynamique des IDL en production ;
- les squelettes réservés ne sont pas des implémentations ;

40
kb-logging/CHANGELOG.md Normal file
View File

@@ -0,0 +1,40 @@
<!-- file: kb-logging/CHANGELOG.md -->
<!-- version: 2 -->
# CHANGELOG — kb-logging
## 0.1.0-pre.069-fix-001
### Corrigé
- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
- retrait des travaux futurs du changelog.
### Documentation
- réécriture de `TODO.md` sous forme de tâches uniquement ;
- correction de `USAGE.md` pour ne conserver que les contraintes runtime durables.
## 0.1.0-pre.069
### Documentation
- création de `TODO.md`, `USAGE.md` et du changelog détaillé ;
- réécriture du README selon la séparation bot3 entre configuration et runtime logging.
## 0.1.0
### Migré
- migration du runtime de logging et tracing depuis bot2 ;
- consolidation des routes console/fichier, formats, rotations et filtres de targets.
### Modifié
- adoption des règles Rust 2024 et Khadhroony ;
- erreurs structurées via `kb_core::Error` ;
- conservation explicite des guards non bloquants.
### Validation
- tests des routes, formats, niveaux, wildcards, writers et targets canoniques du workspace.

48
kb-logging/README.md
View File

@@ -1,38 +1,38 @@
<!-- file: kb-logging/README.md -->
<!-- version: 5 -->
<!-- version: 3 -->
# kb-logging
`kb-logging` initialise le routage `tracing` commun du workspace.
`kb-logging` initialise le subscriber global `tracing` à partir d’une configuration de routes explicites vers la console ou des fichiers.
## Responsabilité
## Responsabilités
Le crate transforme la configuration du profil actif en layers `tracing_subscriber` et route les événements vers la console, les fichiers humains et les fichiers JSONL. Le `LoggingGuard` retourné par `init_logging` doit rester vivant pendant toute la durée du processus afin de conserver les writers non bloquants.
- sélectionner les routes activées ;
- appliquer niveaux, targets exactes et préfixes wildcard ;
- créer les writers non bloquants ;
- gérer les formats human, compact, pretty et JSON ;
- gérer les rotations de fichiers supportées ;
- conserver les `WorkerGuard` pendant toute la durée du processus.
Les décisions de niveau et de target sont appliquées par chaque writer de route, avec un seul filtre d’admission agrégé en amont. Elles ne créent pas un `Filtered` layer par sortie : `tracing-subscriber` réserve seulement 64 identifiants de filtres par subscriber, tandis que la matrice complète comporte désormais plus de 64 routes activables. Le filtrage writer conserve les niveaux, targets exacts, préfixes et overrides configurés sans imposer cette limite au nombre de sorties ; le filtre agrégé évite de formater un événement qu’aucune route n’accepte.
## Hors périmètre
Les chemins relatifs sont résolus depuis la racine du workspace. L’ANSI est désactivé dans les formatters fichier et retiré une seconde fois par `StripAnsiMakeWriter` afin de nettoyer les messages provenant d’une WebView ou d’une dépendance externe.
La crate ne charge pas le fichier de configuration et ne définit pas les targets des autres crates. `kb-config` fournit les valeurs et chaque crate publie son propre target canonique.
## Contrat de targets
## API publique
`kb-logging` utilise le target canonique `kb-logging`, défini dans `src/constants.rs`. Chaque crate qui dépend de `tracing` doit suivre le même contrat avec son propre nom Cargo.
- `init_logging` initialise le subscriber global ;
- `LoggingConfig`, `LogTargetConfig` et `LogTargetFilterConfig` décrivent les routes ;
- `LoggingGuard` maintient les writers et expose les routes installées ;
- `tracing_target` retourne le target canonique de la crate ;
- `LogFileRoute` reste disponible pour les anciens appelants file-only.
Le test `every_tracing_crate_has_one_canonical_target_constant` inspecte les manifests du workspace et vérifie qu’une crate déclarant `tracing.workspace = true` possède exactement une constante conforme.
## Statut
## Matrice de fichiers
L’initialisation multi-routes est fonctionnelle. Elle échoue explicitement si aucune route n’est activée ou si le subscriber global a déjà été initialisé.
Chaque profil actif configure :
## Documents
```text
logs/<profile>/debug.log
logs/<profile>/info.log
logs/<profile>/error.jsonl
logs/<profile>/app.log
logs/<profile>/<crate>/debug.log
logs/<profile>/<crate>/info.log
logs/<profile>/<crate>/error.jsonl
```
Les fichiers sont en rotation quotidienne. Les routes `debug` et `info` sont cumulatives ; les routes `error.jsonl` sont forcées au niveau `error` et n’ajoutent pas les overrides verbeux des dépendances.
Le contrat détaillé se trouve dans `docs/LOGGING.md` et `docs/TRACING_CONTRACT.md`.
- [Utilisation](USAGE.md)
- [Travaux restants](TODO.md)
- [Historique](CHANGELOG.md)
- [Guide de configuration](../kb-config/USAGE.md)

11
kb-logging/TODO.md Normal file
View File

@@ -0,0 +1,11 @@
<!-- file: kb-logging/TODO.md -->
<!-- version: 2 -->
# TODO — kb-logging
## Série 0.5.x — configuration logging dédiée
- [ ] définir avec `kb-config` le contrat de la future configuration logging séparée ;
- [ ] préserver la compatibilité des targets, niveaux, filtres, formats et routes pendant la migration ;
- [ ] ajouter les tests de migration du format de configuration ;
- [ ] mettre à jour les exemples et la documentation après implémentation du nouveau chargement.

67
kb-logging/USAGE.md Normal file
View File

@@ -0,0 +1,67 @@
<!-- file: kb-logging/USAGE.md -->
<!-- version: 2 -->
# Utilisation de kb-logging
## Initialisation
```rust
let config = kb_logging::LoggingConfig {
default_level: "info".to_string(),
targets: vec![kb_logging::LogTargetConfig {
name: "console".to_string(),
enabled: true,
sink: "console".to_string(),
level: "info".to_string(),
path: String::new(),
rotation: "none".to_string(),
format: "compact".to_string(),
ansi: true,
targets: vec!["kb-*".to_string()],
}],
target_filters: Vec::new(),
};
let guard = match kb_logging::init_logging(&config) {
Ok(value) => value,
Err(error) => return Err(error),
};
```
`init_logging` doit être appelée une seule fois par processus. Le `LoggingGuard` retourné doit rester vivant jusqu’à l’arrêt afin de ne pas interrompre les writers non bloquants.
## Inspection des routes
```rust
assert_eq!(guard.route_count(), 1);
assert_eq!(guard.guard_count(), 1);
assert_eq!(guard.route_names(), &["console".to_string()]);
```
## Routes fichier
Pour une route `file`, `path` doit désigner le fichier cible et `rotation` doit être une valeur supportée (`none`, `never`, `daily` ou `hourly`). Les formats supportés sont `human`, `compact`, `pretty` et `json`.
## Filtres de targets
Les routes acceptent des targets exactes et des préfixes wildcard. Les `target_filters` ajoutent des niveaux spécifiques aux routes wildcard. Une route d’erreur conserve la sémantique stricte prévue par l’implémentation.
## Erreurs
Les erreurs utilisent `kb_core::Error`. Les cas principaux sont :
- aucune route activée ;
- sink, format, rotation ou niveau inconnu ;
- chemin fichier invalide ;
- échec d’initialisation du subscriber global.
## Tests instructifs
- `enabled_routes_keep_all_configured_outputs` vérifie l’installation multi-routes ;
- `route_writer_filter_preserves_target_and_level_semantics` vérifie l’admission finale ;
- `more_than_64_routes_compose_without_filtered_layer_ids` couvre un volume élevé de routes ;
- `every_tracing_crate_exposes_canonical_targets` vérifie la cohérence des targets du workspace.
## Limites
- initialisation globale unique par processus ;
- configuration fournie par l’appelant ;

42
kb-store/CHANGELOG.md Normal file
View File

@@ -0,0 +1,42 @@
<!-- file: kb-store/CHANGELOG.md -->
<!-- version: 2 -->
# CHANGELOG — kb-store
## 0.1.0-pre.069-fix-001
### Corrigé
- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
- retrait des constats sans action du TODO et des travaux futurs du changelog.
### Documentation
- réécriture de `TODO.md` sous forme de tâches uniquement ;
- correction des exemples de `USAGE.md` afin de ne pas utiliser l’opérateur `?`.
## 0.1.0-pre.069
### Documentation
- création de `TODO.md`, `USAGE.md` et du changelog détaillé ;
- réécriture du README autour des contrats consolidés et de `PostgresStore`.
## 0.1.0
### Migré
- consolidation de `kb_store_core`, `kb_store_pg` et des contrats associés dans `kb-store` ;
- migration des tables raw, observations, Core, ledger, événements décodés, couverture et matérialisations ;
- migration des migrations SQL, diagnostics et requêtes de replay.
### Modifié
- adoption de Rust 2024 et des règles Khadhroony ;
- maintien des modules internes privés derrière une façade publique contrôlée ;
- erreurs structurées via `kb_core::Error` et transactions async via `sqlx`.
### Validation
- tests des DTO, pagination, filtres, schéma, migrations, diagnostics et atomicité ;
- tests PostgreSQL réels optionnels pilotés par environnement.

142
kb-store/README.md
View File

@@ -1,126 +1,52 @@
<!-- file: kb-store/README.md -->
<!-- version: 1 -->
<!-- version: 3 -->
# `kb-store`
# kb-store
`kb-store` regroupe les contrats de persistance neutres et l’adaptateur PostgreSQL de production de Khadhroony Bot3.
`kb-store` consolide les contrats de stockage et l’implémentation PostgreSQL de `khadhroony-bot3`.
La crate remplace l’ancienne séparation physique entre contrats et PostgreSQL, sans mélanger leurs responsabilités. Tous les modules restent privés et l’API stable est réexportée depuis `src/lib.rs`.
## Périmètre
## Architecture
La crate expose :
```text
src/
├── lib.rs
├── constants.rs
├── contracts.rs
├── contracts/
│ ├── dto.rs
│ ├── dto/
│ ├── entity.rs
│ ├── entity/
│ ├── error.rs
│ ├── health.rs
│ ├── pagination.rs
│ └── repository.rs
├── postgres.rs
└── postgres/
├── migrations.rs
├── query.rs
├── query/
├── replay_candidates.rs
├── repository.rs
├── repository/
├── store.rs
└── test_serial.rs
```
- DTO et entités raw, observations, Core, décodage, matérialisation et ledger ;
- traits async de repositories indépendants du backend ;
- pagination et filtres bornés ;
- `PostgresStore` et ses options de connexion ;
- initialisation idempotente du schéma et migrations SQL ;
- diagnostics read-only, healthchecks et résumés de replay ;
- transactions atomiques pour extraction, décodage et matérialisation.
`contracts` ne dépend d’aucun backend. `postgres` implémente ces contrats avec `sqlx`. `lib.rs` ne contient aucune logique métier.
## Responsabilités
## Direction des dépendances
- garantir les invariants des données persistées ;
- séparer contrats et implémentation PostgreSQL à l’intérieur de la crate consolidée ;
- maintenir les tables canoniques `kb_sol_*` ;
- fournir au pipeline des frontières async typées ;
- protéger les opérations multi-tables par transactions ;
- borner toutes les requêtes de diagnostic et de replay exposées.
```text
kb-core
↑
kb-lib ← kb-store
```
## Hors périmètre
`MdCoreInstructionReplayInput` et sa version de contrat appartiennent à `kb-lib`, car ils sont partagés avec les décodeurs. `kb-store` les consomme et les réexporte. `kb-lib` ne dépend jamais de `kb-store`.
La crate ne décode pas les instructions, n’acquiert pas les transactions et ne décide pas quelle matérialisation exécuter. Elle persiste les résultats produits par `kb-lib` et orchestrés par `kb-pipeline`.
`kb-store` ne dépend pas de `kb-config`. L’application résout sa configuration, puis construit explicitement `PostgresStoreOptions`. Cette séparation évite de coupler la persistance à la forme évolutive des profils.
## API publique
## Contrats publics
Les consommateurs utilisent principalement `PostgresStore`, `PostgresStoreOptions`, les traits `*Store`, les DTO `*Insert`/`*Row`, les filtres de replay et les diagnostics. Les constantes de tables et fonctions de validation sont publiques pour les audits et outils d’administration.
Les familles principales sont :
## Relations
- transactions raw et observations d’acquisition ;
- graphe core Solana : transaction, comptes, instructions, inner instructions, logs et balances ;
- sélection et lifecycle de replay ;
- extraction core atomique ;
- décodage, couverture et matérialisation atomiques ;
- ledger de traitement versionné ;
- santé, migrations et pagination bornée.
- dépend de `kb-core` pour les erreurs ;
- utilise les contrats de replay de `kb-lib` ;
- est consommée principalement par `kb-pipeline`, les scénarios de démonstration et le desktop.
Les traits publics sont :
## Statut
- `StoreHealthStore` ;
- `RawTransactionStore` ;
- `CoreTransactionStore` ;
- `CoreExtractionStore` ;
- `DecodePipelineStore` ;
- `ProgramObservationStore` ;
- `DecodedEventStore` ;
- `MaterializedEventStore` ;
- `ProcessingLedgerStore`.
Le stockage consolidé dispose de tests unitaires étendus et de tests PostgreSQL optionnels pilotés par environnement. Les opérations réelles exigent un serveur PostgreSQL et l’application préalable des migrations.
## PostgreSQL
`PostgresStore` fournit :
- connexion depuis `PostgresStoreOptions` validées ;
- création depuis un `sqlx::PgPool` existant ;
- initialisation idempotente des tables raw, core, decode, materialization et ledger ;
- diagnostics de backend, migrations et tables ;
- sélections bornées de candidats de replay ;
- implémentations des traits store-neutral.
Les transactions raw sont immuables. Les écritures core, decode et materialization conservent leur lineage et utilisent le ledger pour le skip version/hash, le force replay et l’idempotence.
Exemple :
```rust
let options = match kb_store::PostgresStoreOptions::new(
database_url,
8,
5_000,
true,
) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let store = match kb_store::PostgresStore::connect(options).await {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
return std::result::Result::Ok(store);
```
## Validation
```bash
cargo fmt --all
cargo check -p kb-store
cargo test -p kb-store
cargo clippy -p kb-store --all-targets
KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
cargo test -p kb-store -- --nocapture
```
La validation complète du jalon ajoute :
```bash
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
```
## Documents
- [Utilisation](USAGE.md)
- [Travaux restants](TODO.md)
- [Historique](CHANGELOG.md)
- [Architecture du stockage](../docs/architecture/STORAGE_ARCHITECTURE.md)

18
kb-store/TODO.md Normal file
View File

@@ -0,0 +1,18 @@
<!-- file: kb-store/TODO.md -->
<!-- version: 2 -->
# TODO — kb-store
## Maintenance des contrats de stockage
- [ ] auditer toute nouvelle requête afin de garantir une borne explicite ;
- [ ] vérifier le caractère read-only des nouvelles requêtes de diagnostic ;
- [ ] conserver une séparation nette entre les contrats publics et les détails SQL internes ;
- [ ] ajouter un test PostgreSQL réel pour chaque nouvelle migration ;
- [ ] ajouter un test d’atomicité pour chaque nouvelle transaction multi-tables ;
- [ ] compléter le guide transversal d’exploitation PostgreSQL lors de l’ajout des procédures administratives.
## Extensions futures
- [ ] définir les outils d’administration supplémentaires prévus par le ROADMAP avant leur implémentation ;
- [ ] documenter et tester les futures opérations historiques ajoutées à la crate.

88
kb-store/USAGE.md Normal file
View File

@@ -0,0 +1,88 @@
<!-- file: kb-store/USAGE.md -->
<!-- version: 2 -->
# Utilisation de kb-store
## Connexion PostgreSQL
```rust
let options = match kb_store::PostgresStoreOptions::new(
database_url,
"public".to_string(),
10,
std::time::Duration::from_secs(10),
) {
Ok(value) => value,
Err(error) => return Err(error),
};
let store = match kb_store::PostgresStore::connect(options).await {
Ok(value) => value,
Err(error) => return Err(error),
};
if let Err(error) = store.initialize_store_schema().await {
return Err(error);
}
```
`PostgresStoreOptions::new` valide le DSN, le schéma, le nombre de connexions et le timeout. Utiliser `masked_dsn` ou `mask_postgres_dsn` dans les logs ; ne jamais journaliser le DSN brut.
## Diagnostics
```rust
let health = store.health_snapshot().await;
let migrations = store.migration_snapshot().await;
let backend = store.backend_diagnostics().await;
```
Les diagnostics de tables raw, Core et decode/materialization sont également disponibles par les méthodes `*_table_diagnostics`.
## Contrats de repositories
Les traits publics principaux sont :
- `StoreHealthStore` ;
- `RawTransactionStore` ;
- `CoreTransactionStore` ;
- `CoreExtractionStore` ;
- `DecodePipelineStore` ;
- `ProgramObservationStore` ;
- `DecodedEventStore` ;
- `MaterializedEventStore` ;
- `ProcessingLedgerStore`.
Ils permettent au pipeline de dépendre d’un contrat async plutôt que d’une requête SQL directe.
## Replay et requêtes bornées
```rust
let candidates = store.replay_transaction_candidates(filter).await;
let programs = store.replay_program_summaries(program_filter).await;
let entities = store.replay_entity_summaries(entity_filter).await;
```
Les filtres refusent les limites nulles ou supérieures aux bornes publiques. `PageRequest` impose également `DEFAULT_PAGE_SIZE` et `MAX_PAGE_SIZE`.
## Transactions atomiques
Les bundles `CoreExtractionBundle`, `DecodePersistenceBundle` et `MaterializationPersistenceBundle` regroupent les écritures qui doivent réussir ou être annulées ensemble. Les consommateurs ne doivent pas reproduire manuellement ces transactions avec des écritures isolées.
## Schéma et tables
Les constantes `RAW_STORE_TABLE_NAMES`, `CORE_STORE_TABLE_NAMES` et `DECODE_STORE_TABLE_NAMES` exposent les noms canoniques. Les fonctions `validate_*_table_names` et `is_valid_solana_table_name` servent aux audits et outils d’administration.
## Erreurs et invariants
Toutes les APIs utilisent `kb_core::Result`. Les DTO valident notamment les signatures, chemins, Program IDs, clés, montants, états de traitement et identités de ledger. Les erreurs de contrat peuvent être construites avec `storage_contract_error`.
## Tests instructifs
- les tests `*_rejects_*` documentent les invariants des DTO et filtres ;
- `decoded_events_and_ledger_roll_back_together` vérifie l’atomicité ;
- `optional_postgres_*_from_env` couvre les parcours réels lorsque l’environnement PostgreSQL est configuré ;
- les tests de schéma vérifient les noms, index, contraintes et migrations.
## Limites
- backend actif : PostgreSQL ;
- les tests réels sont optionnels sans DSN de test ;
- la crate ne prend aucune décision de décodage ou de matérialisation.