0.5.1-pre.002

This commit is contained in:
2026-08-09 19:34:08 +02:00
parent 816eee59a9
commit 6a680767ae
767 changed files with 12257 additions and 12195 deletions

View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/ARCHITECTURE.md -->
<!-- version: 6 -->
<!-- version: 7 -->
# Architecture générale
@@ -12,7 +12,7 @@ configuration ─────┐
logging ───────────┼──────────────┐
program IDs ───────┘ │
v
transport -> store -> pipeline -> kb-lib
transport -> store -> pipeline -> ks-lib
│ │
v v
demo scenarios wallet/signers
@@ -28,32 +28,32 @@ Cette représentation indique les relations dominantes. Elle ne remplace pas le
### 2.1 Fondations
- `kb-core` fournit les erreurs et identités transversales minimales.
- `kb-config` charge, résout et valide la configuration.
- `kb-logging` initialise le logging et le tracing.
- `kb-program-ids` centralise les identifiants de programmes et comptes connus.
- `ks-core` fournit les erreurs et identités transversales minimales.
- `ks-config` charge, résout et valide la configuration.
- `ks-logging` initialise le logging et le tracing.
- `ks-program-ids` centralise les identifiants de programmes et comptes connus.
### 2.2 Noyau métier
`kb-lib` contient quatre familles principales :
`ks-lib` contient quatre familles principales :
- modèles et contrats partagés ;
- décodeurs ;
- exécuteurs ;
- matérialisateurs.
La façade publique est constituée par les réexports de `kb-lib/src/lib.rs`. Les modules internes conservent leurs frontières et leurs conventions de nommage.
La façade publique est constituée par les réexports de `ks-lib/src/lib.rs`. Les modules internes conservent leurs frontières et leurs conventions de nommage.
### 2.3 Acquisition et stockage
- `kb-onchain-transport` fournit les clients HTTP/WebSocket, pools, rôles dendpoints, méthodes RPC standard et contrats liés à lexécution RPC.
- `kb-store` regroupe les contrats store-neutral et limplémentation PostgreSQL.
- `ks-onchain-transport` fournit les clients HTTP/WebSocket, pools, rôles dendpoints, méthodes RPC standard et contrats liés à lexécution RPC.
- `ks-store` regroupe les contrats store-neutral et limplémentation PostgreSQL.
Les transports neffectuent pas la matérialisation métier. Le stockage ne décide pas quelle surface protocolaire doit être décodée.
### 2.4 Orchestration
`kb-pipeline` orchestre :
`ks-pipeline` orchestre :
- backfill ;
- extraction Core ;
@@ -62,14 +62,14 @@ Les transports neffectuent pas la matérialisation métier. Le stockage ne d
- corrélation stateful ;
- préflight et orchestration dexécution pour les surfaces prises en charge.
Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacités de `kb-onchain-transport` sans absorber leurs responsabilités.
Il dépend des contrats de `ks-lib`, des données de `ks-store` et des capacités de `ks-onchain-transport` sans absorber leurs responsabilités.
### 2.5 Démonstrations et applications
- `kb-pipeline-demo-scenarios` fournit les fixtures et campagnes réseau réutilisables spécifiques aux validations Devnet/Testnet. Les scénarios réutilisables doivent être appelables sans dépendre du desktop.
- Le binaire `kb-pipeline-demo-scenarios-cli` reste un outil ciblé ; son existence nimpose pas dexposer chaque scénario par un CLI.
- `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop. Les commandes et projections UI y restent, tandis que la logique de scénario réutilisable doit être déléguée à `kb-pipeline-demo-scenarios`. Le reliquat éventuel de scénarios encore déclarés directement dans le desktop sera audité en `0.5.4`.
- `kb-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Elle devient `ks-wallet` en `0.5.1`, puis sa restructuration fonctionnelle est planifiée en `0.5.2`.
- `ks-pipeline-demo-scenarios` fournit les fixtures et campagnes réseau réutilisables spécifiques aux validations Devnet/Testnet. Les scénarios réutilisables doivent être appelables sans dépendre du desktop.
- Le binaire `ks-pipeline-demo-scenarios-cli` reste un outil ciblé ; son existence nimpose pas dexposer chaque scénario par un CLI.
- `kb-app-demo-desktop` est une crate mixte : bibliothèque Tauri et binaire desktop. Les commandes et projections UI y restent, tandis que la logique de scénario réutilisable doit être déléguée à `ks-pipeline-demo-scenarios`. Le reliquat éventuel de scénarios encore déclarés directement dans le desktop sera audité en `0.5.4`.
- `ks-wallet` fournit actuellement une frontière limitée de wallet temporaire et de signataire. Elle devient `ks-wallet` en `0.5.1`, puis sa restructuration fonctionnelle est planifiée en `0.5.2`.
## 3. Flux principal de données
@@ -77,18 +77,18 @@ Il dépend des contrats de `kb-lib`, des données de `kb-store` et des capacité
Solana RPC / WebSocket
v
kb-onchain-transport
ks-onchain-transport
v
kb-store (données brutes/canoniques)
ks-store (données brutes/canoniques)
v
kb-pipeline
ks-pipeline
├── extraction Core
├── sélection des décodeurs
├── décodage via kb-lib
├── matérialisation via kb-lib
├── décodage via ks-lib
├── matérialisation via ks-lib
└── stockage des résultats
```
@@ -96,11 +96,11 @@ Lexécution suit un flux séparé : intention typée, construction, préfligh
## 4. Frontières obligatoires
- Les IDs canoniques ne doivent pas être dispersés lorsquils appartiennent au registre de `kb-program-ids`.
- Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `kb-lib`.
- Les IDs canoniques ne doivent pas être dispersés lorsquils appartiennent au registre de `ks-program-ids`.
- Les APIs publiques de modèles, décodeurs, exécuteurs et matérialisateurs sont exposées par `ks-lib`.
- Les commandes Tauri et payloads frontend spécifiques restent dans `kb-app-demo-desktop`.
- Les scénarios réseau réutilisables spécifiques à Devnet/Testnet appartiennent à `kb-pipeline-demo-scenarios`, future `ks-pipeline-demo-scenarios`. `kb-app-demo-desktop` doit se limiter à ladaptation Tauri, aux payloads UI, à la présentation et à lappel de ces scénarios ; les doublons résiduels seront réconciliés en `0.5.4`.
- Toute primitive ou orchestration réellement généraliste, indépendante de lUI et dune campagne de démonstration précise, appartient à `kb-pipeline` ou à la crate métier propriétaire.
- Les scénarios réseau réutilisables spécifiques à Devnet/Testnet appartiennent à `ks-pipeline-demo-scenarios`, future `ks-pipeline-demo-scenarios`. `kb-app-demo-desktop` doit se limiter à ladaptation Tauri, aux payloads UI, à la présentation et à lappel de ces scénarios ; les doublons résiduels seront réconciliés en `0.5.4`.
- Toute primitive ou orchestration réellement généraliste, indépendante de lUI et dune campagne de démonstration précise, appartient à `ks-pipeline` ou à la crate métier propriétaire.
- Les fixtures contractuelles communes restent sous `test-fixtures/contract-matrices/` lorsquelles sont consommées par plusieurs tests.
- Les archives documentaires ne participent ni au build ni aux décisions normatives.

View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/CRATE_MAP.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Carte des crates
@@ -7,16 +7,16 @@
| Crate | Type | Responsabilité principale | État documentaire |
|------------------------------|------------------------|--------------------------------------------------------------------|------------------------------------------|
| `kb-core` | bibliothèque | erreurs, résultat et identité de module partagés | README/TODO/USAGE/CHANGELOG présents |
| `kb-config` | bibliothèque | configuration JSON, environnement, validation et profils | migration/restructuration en `0.5.1` |
| `kb-lib` | bibliothèque | modèles, décodeurs, exécuteurs et matérialisateurs consolidés | README/TODO/USAGE/CHANGELOG présents |
| `kb-logging` | bibliothèque | initialisation du logging et du tracing | README/TODO/USAGE/CHANGELOG présents |
| `kb-program-ids` | bibliothèque | registre des programmes et comptes Solana connus | README/TODO/USAGE/CHANGELOG présents |
| `kb-pipeline` | bibliothèque | backfill, extraction, replay, stateful, préflight et orchestration | README/TODO/USAGE/CHANGELOG présents |
| `kb-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI | renommage `0.5.1`, audit `0.5.4` |
| `kb-onchain-transport` | bibliothèque | transports RPC HTTP/WebSocket et pools dendpoints | README/TODO/USAGE/CHANGELOG présents |
| `kb-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | renommage `0.5.1`, normalisation `0.5.3` |
| `kb-wallet` | bibliothèque | wallet temporaire et frontière de signataire | renommage `0.5.1`, refonte `0.5.2` |
| `ks-core` | bibliothèque | erreurs, résultat et identité de module partagés | README/TODO/USAGE/CHANGELOG présents |
| `ks-config` | bibliothèque | configuration JSON, environnement, validation et profils | migration/restructuration en `0.5.1` |
| `ks-lib` | bibliothèque | modèles, décodeurs, exécuteurs et matérialisateurs consolidés | README/TODO/USAGE/CHANGELOG présents |
| `ks-logging` | bibliothèque | initialisation du logging et du tracing | README/TODO/USAGE/CHANGELOG présents |
| `ks-program-ids` | bibliothèque | registre des programmes et comptes Solana connus | README/TODO/USAGE/CHANGELOG présents |
| `ks-pipeline` | bibliothèque | backfill, extraction, replay, stateful, préflight et orchestration | README/TODO/USAGE/CHANGELOG présents |
| `ks-pipeline-demo-scenarios` | bibliothèque + binaire | scénarios Devnet réutilisables et CLI | renommage `0.5.1`, audit `0.5.4` |
| `ks-onchain-transport` | bibliothèque | transports RPC HTTP/WebSocket et pools dendpoints | README/TODO/USAGE/CHANGELOG présents |
| `ks-store` | bibliothèque | contrats de stockage et adaptateur PostgreSQL | renommage `0.5.1`, normalisation `0.5.3` |
| `ks-wallet` | bibliothèque | wallet temporaire et frontière de signataire | renommage `0.5.1`, refonte `0.5.2` |
| `kb-app-demo-desktop` | bibliothèque + binaire | application de démonstration Tauri | documentée ; réconciliation en `0.5.4` |
La table décrit les noms physiques du workspace `0.5.0`. La migration `0.5.1` renomme les dix crates généralistes en `ks-core`, `ks-config`, `ks-lib`, `ks-logging`, `ks-program-ids`, `ks-pipeline`, `ks-pipeline-demo-scenarios`, `ks-onchain-transport`, `ks-store` et `ks-wallet`. `kb-app-demo-desktop` conserve son nom parce quil appartient au domaine applicatif Bot. Voir [`../decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`](../decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md).
@@ -25,21 +25,21 @@ La table décrit les noms physiques du workspace `0.5.0`. La migration `0.5.1` r
La migration a regroupé de nombreuses anciennes crates dans des frontières plus larges :
- les modèles et APIs de décodage, matérialisation et exécution ont rejoint `kb-lib` ;
- les implémentations de stockage core et PostgreSQL ont rejoint `kb-store` ;
- les responsabilités de pipeline ont été réunies dans `kb-pipeline` ;
- les transports Solana sont réunis dans `kb-onchain-transport` ;
- les modèles et APIs de décodage, matérialisation et exécution ont rejoint `ks-lib` ;
- les implémentations de stockage core et PostgreSQL ont rejoint `ks-store` ;
- les responsabilités de pipeline ont été réunies dans `ks-pipeline` ;
- les transports Solana sont réunis dans `ks-onchain-transport` ;
- lapplication et sa bibliothèque sont réunies dans `kb-app-demo-desktop` ;
- les scénarios réutilisables ont été extraits dans `kb-pipeline-demo-scenarios`.
- les scénarios réutilisables ont été extraits dans `ks-pipeline-demo-scenarios`.
Cette carte nest pas une table de compatibilité exhaustive des anciennes crates. Les correspondances historiques détaillées seront synthétisées dans la documentation de migration et laudit dalignement.
## 3. Crates mixtes
### 3.1 `kb-pipeline-demo-scenarios`
### 3.1 `ks-pipeline-demo-scenarios`
- bibliothèque Rust : `kb_pipeline_demo_scenarios` ;
- binaire : `kb-pipeline-demo-scenarios-cli` ;
- bibliothèque Rust : `ks_pipeline_demo_scenarios` ;
- binaire : `ks-pipeline-demo-scenarios-cli` ;
- `autobins = false` évite une cible implicite concurrente.
### 3.2 `kb-app-demo-desktop`

View File

@@ -1,11 +1,11 @@
<!-- file: docs/architecture/PIPELINE_ARCHITECTURE.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Architecture du pipeline
## 1. Responsabilité
`kb-pipeline` coordonne des opérations généralistes qui traversent plusieurs crates sans devenir propriétaire de leurs implémentations : transport, stockage, contrats de décodage, matérialisation et exécution. Il ne dépend daucun scénario, wallet ou actif propre à un réseau de démonstration.
`ks-pipeline` coordonne des opérations généralistes qui traversent plusieurs crates sans devenir propriétaire de leurs implémentations : transport, stockage, contrats de décodage, matérialisation et exécution. Il ne dépend daucun scénario, wallet ou actif propre à un réseau de démonstration.
## 2. Familles de traitements
@@ -19,7 +19,7 @@ Lextraction Core transforme les transactions stockées en représentations d
### 2.3 Replay de décodage
Le replay sélectionne des candidats, applique les décodeurs compatibles de `kb-lib`, conserve diagnostics et preuves, puis déclenche les matérialisateurs demandés. La reprise doit préserver lidempotence et les frontières de campagne.
Le replay sélectionne des candidats, applique les décodeurs compatibles de `ks-lib`, conserve diagnostics et preuves, puis déclenche les matérialisateurs demandés. La reprise doit préserver lidempotence et les frontières de campagne.
### 2.4 Traitements stateful
@@ -27,28 +27,28 @@ Les modules stateful corrèlent instructions, comptes, états précédents et r
### 2.5 Préflight et exécution
Le pipeline assemble les contrôles préalables, plans préparés, signataires, preuves, simulation et validation postérieure. Les exécuteurs restent définis dans `kb-lib` ; le pipeline orchestre leur utilisation.
Le pipeline assemble les contrôles préalables, plans préparés, signataires, preuves, simulation et validation postérieure. Les exécuteurs restent définis dans `ks-lib` ; le pipeline orchestre leur utilisation.
## 3. Dépendances fonctionnelles
```text
kb-onchain-transport -> acquisition et appels RPC
kb-store -> lecture/écriture canonique et replay
kb-lib -> contrats et implémentations métier
kb-config -> profils et paramètres opérationnels
kb-logging -> observabilité
kb-wallet -> signataires lorsque requis
ks-onchain-transport -> acquisition et appels RPC
ks-store -> lecture/écriture canonique et replay
ks-lib -> contrats et implémentations métier
ks-config -> profils et paramètres opérationnels
ks-logging -> observabilité
ks-wallet -> signataires lorsque requis
```
## 4. Scénarios de démonstration
`kb-pipeline-demo-scenarios` contient les fixtures, aides de campagne et scénarios réutilisables spécifiques à Devnet ou Testnet. Le desktop doit appeler ces scénarios lorsquils existent plutôt que maintenir une seconde implémentation métier du même parcours.
`ks-pipeline-demo-scenarios` contient les fixtures, aides de campagne et scénarios réutilisables spécifiques à Devnet ou Testnet. Le desktop doit appeler ces scénarios lorsquils existent plutôt que maintenir une seconde implémentation métier du même parcours.
Cette crate peut préparer des wallets temporaires, demander des airdrops, créer des mints ou comptes de test, enchaîner plusieurs opérations et réunir les preuves dune campagne réseau. Ces responsabilités spécifiques aux validations réseau ne doivent pas remonter dans `kb-pipeline`.
Cette crate peut préparer des wallets temporaires, demander des airdrops, créer des mints ou comptes de test, enchaîner plusieurs opérations et réunir les preuves dune campagne réseau. Ces responsabilités spécifiques aux validations réseau ne doivent pas remonter dans `ks-pipeline`.
Le binaire `kb-pipeline-demo-scenarios-cli` est actuellement un outil ciblé de préparation des fixtures SPL Token-2022 réutilisées par les démonstrations Devnet. Son existence ne signifie pas que chaque scénario doit être exposé par un CLI ni que le desktop doit consommer ses scénarios.
Le binaire `ks-pipeline-demo-scenarios-cli` est actuellement un outil ciblé de préparation des fixtures SPL Token-2022 réutilisées par les démonstrations Devnet. Son existence ne signifie pas que chaque scénario doit être exposé par un CLI ni que le desktop doit consommer ses scénarios.
`kb-app-demo-desktop` conserve ses commandes Tauri, états, payloads et parcours de présentation Devnet/Testnet. La logique réutilisable de préparation et dexécution de campagne appartient à `kb-pipeline-demo-scenarios`, renommée `ks-pipeline-demo-scenarios` en `0.5.1`. `0.5.4` auditera les scénarios encore déclarés directement dans le desktop et déplacera ceux qui sont réutilisables. La dépendance inverse de `kb-pipeline` vers les scénarios reste interdite et cette règle se conserve après migration vers `ks-pipeline`.
`kb-app-demo-desktop` conserve ses commandes Tauri, états, payloads et parcours de présentation Devnet/Testnet. La logique réutilisable de préparation et dexécution de campagne appartient à `ks-pipeline-demo-scenarios`, renommée `ks-pipeline-demo-scenarios` en `0.5.1`. `0.5.4` auditera les scénarios encore déclarés directement dans le desktop et déplacera ceux qui sont réutilisables. La dépendance inverse de `ks-pipeline` vers les scénarios reste interdite et cette règle se conserve après migration vers `ks-pipeline`.
## 5. Contrats de preuve

View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/PROJECT_OBJECTIVES.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Objectifs du projet Khadhroony Bot3
@@ -29,7 +29,7 @@ Le projet vise à :
### 3.1 Consolidation contrôlée
La consolidation ne signifie pas leffacement des frontières métier. `kb-lib` regroupe les modèles, décodeurs, exécuteurs et matérialisateurs dans des modules dédiés. `kb-store`, `kb-pipeline` et `kb-onchain-transport` restent des crates séparées parce quils représentent des responsabilités opérationnelles différentes.
La consolidation ne signifie pas leffacement des frontières métier. `ks-lib` regroupe les modèles, décodeurs, exécuteurs et matérialisateurs dans des modules dédiés. `ks-store`, `ks-pipeline` et `ks-onchain-transport` restent des crates séparées parce quils représentent des responsabilités opérationnelles différentes.
### 3.2 Contrats explicites

View File

@@ -1,11 +1,11 @@
<!-- file: docs/architecture/STORAGE_ARCHITECTURE.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Architecture du stockage
## 1. Responsabilité de `kb-store`
## 1. Responsabilité de `ks-store`
`kb-store` réunit :
`ks-store` réunit :
- les contrats store-neutral ;
- les DTO et entités persistées ;
@@ -34,7 +34,7 @@ Le module PostgreSQL possède :
### 2.3 Modèles partagés
Les modèles métier communs restent dans `kb-lib` lorsquils dépassent la seule persistance. `kb-store` ne doit pas créer une seconde définition concurrente dun contrat partagé.
Les modèles métier communs restent dans `ks-lib` lorsquils dépassent la seule persistance. `ks-store` ne doit pas créer une seconde définition concurrente dun contrat partagé.
## 3. Catégories de données
@@ -47,7 +47,7 @@ Le stockage couvre plusieurs niveaux :
- états de campagne et candidats de replay ;
- informations opérationnelles et de santé.
Les noms de tables, contrats de replay et APIs publiques sont documentés dans `kb-store/USAGE.md` à partir des exports et migrations actuels.
Les noms de tables, contrats de replay et APIs publiques sont documentés dans `ks-store/USAGE.md` à partir des exports et migrations actuels.
## 4. Propriétés attendues

View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/SURFACE_CRATE_MATRIX.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Matrice des responsabilités par surface
@@ -13,7 +13,7 @@
## 2. Matrice
| Surface | `kb-lib` | `kb-pipeline` | `kb-store` | `kb-onchain-transport` | `kb-pipeline-demo-scenarios` | `kb-app-demo-desktop` |
| Surface | `ks-lib` | `ks-pipeline` | `ks-store` | `ks-onchain-transport` | `ks-pipeline-demo-scenarios` | `kb-app-demo-desktop` |
|---------------------------|--------------------------------------------------------------------------------|------------------------------------------------------|-----------------------|-------------------------------|--------------------------------------------------------|-----------------------------------------------------|
| Solana Core | décodeurs, exécuteurs et matérialisateurs | extraction, replay, stateful et exécution | persistance générique | RPC HTTP/WS | validations Devnet | panneaux fonctionnels |
| SPL Memo | décodage v1/v3/v4 ; exécution v4 | replay et exécution v4 | persistance générique | RPC | scénario Memo v4 | panneau Memo v4 |
@@ -29,7 +29,7 @@
Cette matrice décrit les responsabilités observées au niveau architectural. Elle ne déclare pas une couverture exhaustive de chaque instruction ou compte. La couverture détaillée reste démontrée par le code, les tests, les matrices sous `test-fixtures/contract-matrices/` et les rapports de validation actifs ou archivés.
La persistance des surfaces Metadata repose sur les contrats génériques de decode/materialization de `kb-store`. Leur séparation métier est portée notamment par les identités de processeur, les familles matérialisées, les clés de sortie et les payloads versionnés ; `0.4.8` nintroduit donc pas de schéma PostgreSQL spécialisé par protocole Metadata.
La persistance des surfaces Metadata repose sur les contrats génériques de decode/materialization de `ks-store`. Leur séparation métier est portée notamment par les identités de processeur, les familles matérialisées, les clés de sortie et les payloads versionnés ; `0.4.8` nintroduit donc pas de schéma PostgreSQL spécialisé par protocole Metadata.
## 4. Statuts sensibles
@@ -38,4 +38,4 @@ La persistance des surfaces Metadata repose sur les contrats génériques de dec
- Solana Program Metadata est couvert par neuf opérations stables, toutes validées sur Devnet.
- Token-2022 Token Metadata est couvert par cinq opérations dinterface, toutes validées sur Devnet.
- Metaplex Token Metadata est clos pour la matrice courante de `0.4.8` avec 15 opérations `confirmed`, 5 `unavailable` et 0 `not_run` ; les opérations indisponibles ne doivent pas être promues sans nouvelle preuve réseau.
- La priorité trading des versions suivantes naltère pas la vocation généraliste de `kb-lib` : les autres Program IDs restent dans le périmètre de couverture et peuvent être différés selon leur priorité de développement.
- La priorité trading des versions suivantes naltère pas la vocation généraliste de `ks-lib` : les autres Program IDs restent dans le périmètre de couverture et peuvent être différés selon leur priorité de développement.