<!-- file: kb-pipeline/README.md -->
<!-- version: 7 -->

# kb-pipeline

`kb-pipeline` est le pipeline généraliste de `khadhroony-bot3`. Il coordonne les transports, le stockage et `kb-lib` sans dépendre d’un scénario de démonstration ni d’un cluster particulier.

## Responsabilités

- backfill HTTP borné ;
- insertion canonique ;
- extraction Core ;
- replay contextualisé ;
- matérialisation optionnelle et idempotente ;
- lectures stateful et corrélations ;
- préflights d’exécution ;
- résolution des signers ;
- orchestration simulation-first, contrôles de readiness et postvalidation ;
- diagnostics stables exploitables par des applications ou scénarios.

Pour Metaplex Token Metadata, la crate expose les lectures stateful bornées, le préflight, la validation de readiness et l’agrégation des postconditions.

Pour Solana Program Metadata, elle expose les mêmes frontières réutilisables pour les neuf opérations stables : lecture `Buffer`/`Metadata`, préflight stateful, gouvernance `ExSafetyChecker`, readiness simulation-first et postconditions. Elle ne contient ni fixture Devnet, ni wallet de démonstration, ni séquence métier spécifique à un test.

## Surface publique principale

- campagnes de backfill et progression ;
- extraction Core et decode replay ;
- inspections stateful Solana Core et SPL ;
- `read_metaplex_token_metadata_stateful_snapshot` ;
- `inspect_metaplex_token_metadata_preflight` ;
- `validate_metaplex_token_metadata_execution_readiness` ;
- `summarize_metaplex_token_metadata_postconditions` ;
- `read_solana_program_metadata_stateful_snapshot` ;
- `inspect_solana_program_metadata_preflight` ;
- `validate_solana_program_metadata_execution_readiness` ;
- `inspect_solana_program_metadata_post_execution`.

Les fichiers internes suivent la même nomenclature que `kb-lib` : préfixe `metadata_` pour les programmes metadata, préfixe `spl_` pour les programmes SPL et préfixe `solana_` uniquement pour les contrats Solana Core transversaux. Les noms des fonctions publiques sont conservés pour éviter une rupture d’API.

Voir [USAGE.md](USAGE.md) pour les exemples et invariants.

## Relations avec le workspace

La crate coordonne `kb-onchain-transport`, `kb-store`, `kb-lib`, `kb-core` et `kb-program-ids`. Elle ne dépend jamais de `kb-pipeline-demo-scenarios` ni de `kb-app-demo-desktop`. Les fixtures, wallets temporaires et appels RPC de démonstration appartiennent aux scénarios ou aux applications qui consomment ces contrats.

## Documentation

- [Guide d’utilisation](USAGE.md)
- [Travaux restant à réaliser](TODO.md)
- [Historique des changements](CHANGELOG.md)
- [Architecture du pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md)