v0.1.0-pre.070

kb-pipeline/CHANGELOG.md

@@ -0,0 +1,20 @@
+<!-- file: kb-pipeline/CHANGELOG.md -->
+<!-- version: 1 -->
+
+# CHANGELOG — kb-pipeline
+
+## 0.1.0-pre.070
+
+- enrichissement du `USAGE.md` avec plusieurs exemples couvrant les principales familles d’API publiques ;
+- ajout du contrat documentaire de la crate ;
+- classement des APIs publiques par campagnes, replay et inspections stateful ;
+- clarification des invariants de déterminisme, bornage et matérialisation ;
+- inscription des travaux Metaplex et ElGamal restants dans le TODO.
+
+## 0.1.0-pre.062
+
+- migration du pipeline bot2 dans l’architecture consolidée bot3 ;
+- reprise du backfill, de l’extraction Core, du decode replay et des matérialisations ;
+- migration des préflights, corrélations et orchestrations Token-2022 ;
+- migration des contrats stateful SPL Token, ATA et registre ElGamal ;
+- adaptation aux normes Rust 2024 et Khadhroony bot3.

kb-pipeline/README.md

@@ -0,0 +1,36 @@
+<!-- file: kb-pipeline/README.md -->
+<!-- version: 1 -->
+
+# kb-pipeline
+
+`kb-pipeline` orchestre les traitements on-chain de `khadhroony-bot3`.
+
+## Responsabilités
+
+- backfill HTTP borné ;
+- extraction des transactions canoniques vers le modèle Core ;
+- replay contextualisé des décodeurs ;
+- matérialisation optionnelle et idempotente ;
+- préflights et inspections stateful ;
+- orchestration Token-2022, preuves et postconditions ;
+- corrélation entre instructions observées et états finaux.
+
+La crate coordonne `kb-onchain-transport`, `kb-store`, `kb-lib`, `kb-core` et `kb-program-ids`. Elle ne contient pas l’interface desktop ni les scénarios opérateur de démonstration.
+
+## Familles publiques
+
+- backfill ;
+- extraction Core ;
+- decode replay ;
+- inspections stateful Solana Core, SPL Token, ATA, Token-2022 et registre ElGamal ;
+- préflight cryptographique et orchestration d’exécution Token-2022.
+
+Voir [USAGE.md](USAGE.md) pour les contrats publics.
+
+## Documentation
+
+- [USAGE.md](USAGE.md)
+- [TODO.md](TODO.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [Architecture du pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md)
+- [Architecture du stockage](../docs/architecture/STORAGE_ARCHITECTURE.md)

kb-pipeline/TODO.md

@@ -0,0 +1,12 @@
+<!-- file: kb-pipeline/TODO.md -->
+<!-- version: 1 -->
+
+# TODO — kb-pipeline
+
+- [ ] Metaplex Token Metadata - intégrer la matérialisation migrée et les étapes restantes au replay bot3.
+- [ ] Metaplex Token Metadata - ajouter l’orchestration nécessaire à l’exécuteur et aux validations de la future `0.4.7`.
+- [ ] Registre ElGamal - confirmer l’existence et le déploiement du programme avant toute campagne réseau.
+- [ ] Registre ElGamal - compléter uniquement les couches pipeline justifiées par un scénario réellement exécutable.
+- [ ] Tests - ajouter les tests ciblés correspondant aux écarts identifiés par l’audit d’alignement `0.4.6`.
+- [ ] Documentation - compléter le guide de replay, extraction Core et matérialisation à partir des contrats bot3.
+- [ ] Dette technique - vérifier les duplications résiduelles entre les orchestrations SPL Token classique et Token-2022.

kb-pipeline/USAGE.md

@@ -0,0 +1,180 @@
+<!-- file: kb-pipeline/USAGE.md -->
+<!-- version: 2 -->
+
+# Utilisation de kb-pipeline
+
+## Objectif
+
+La crate expose les campagnes bornées d’acquisition, d’extraction, de replay et les inspections stateful nécessaires aux applications et scénarios.
+
+## Valider une requête d’extraction Core
+
+```rust
+fn validate_pending_extraction() -> kb_core::Result<()> {
+    let request = kb_pipeline::CoreExtractionRequest {
+        source: kb_pipeline::CoreExtractionSource::Pending,
+        limit: 1_000,
+        max_concurrent_extractions: 4,
+        force_replay: false,
+    };
+
+    request.validate()
+}
+```
+
+Une extraction ciblée peut utiliser `CoreExtractionSource::Signatures`, `SlotRange` ou `ProgramId`.
+
+## Exécuter une campagne d’extraction Core
+
+```rust
+async fn run_core_extraction<S, O>(
+    store: &S,
+    observer: &O,
+    request: kb_pipeline::CoreExtractionRequest,
+) -> kb_core::Result<kb_pipeline::CoreExtractionSummary>
+where
+    S: kb_store::CanonicalTransactionStore
+        + kb_store::CoreExtractionStore
+        + Sync,
+    O: kb_pipeline::CoreExtractionObserver,
+{
+    let result = kb_pipeline::execute_core_extraction(store, observer, request).await;
+
+    match result {
+        Ok(summary) => Ok(summary),
+        Err(error) => Err(error),
+    }
+}
+```
+
+## Préparer une requête de decode replay
+
+```rust
+fn validate_decode_request(
+    selection: kb_store::DecodeSelectionFilter,
+) -> kb_core::Result<()> {
+    let request = kb_pipeline::DecodeReplayRequest {
+        campaign_id: "manual-replay-001".to_string(),
+        selection,
+        decoder_names: Vec::new(),
+        dispatch_policy: kb_pipeline::DecodeDispatchPolicy::HighestPriority,
+        max_concurrent_inputs: 4,
+        force_replay: false,
+        force_replay_all_matching: false,
+        materialize_after_decode: true,
+    };
+
+    request.validate()
+}
+```
+
+Une liste vide dans `decoder_names` signifie que tous les décodeurs fournis à l’orchestrateur restent éligibles.
+
+## Exécuter un decode replay
+
+```rust
+async fn run_decode_replay<S, O>(
+    store: &S,
+    observer: &O,
+    request: kb_pipeline::DecodeReplayRequest,
+    decoders: &[&dyn kb_lib::MdApiInstructionDecoder],
+    materializers: &[&dyn kb_lib::MdApiEventMaterializer],
+) -> kb_core::Result<kb_pipeline::DecodeReplaySummary>
+where
+    S: kb_store::DecodeReplayStore + Sync,
+    O: kb_pipeline::DecodeReplayObserver,
+{
+    let result = kb_pipeline::execute_decode_replay(
+        store,
+        observer,
+        request,
+        decoders,
+        materializers,
+    )
+    .await;
+
+    match result {
+        Ok(summary) => Ok(summary),
+        Err(error) => Err(error),
+    }
+}
+```
+
+## Backfill HTTP
+
+La surface principale utilise `BackfillRequest`, `BackfillObserver`, `execute_http_backfill` et `BackfillSummary`.
+
+```rust
+async fn run_backfill<S, O>(
+    store: &S,
+    observer: &O,
+    request: kb_pipeline::BackfillRequest,
+) -> kb_core::Result<kb_pipeline::BackfillSummary>
+where
+    S: kb_store::CanonicalTransactionStore + Sync,
+    O: kb_pipeline::BackfillObserver,
+{
+    let result = kb_pipeline::execute_http_backfill(store, observer, request).await;
+
+    match result {
+        Ok(summary) => Ok(summary),
+        Err(error) => Err(error),
+    }
+}
+```
+
+## Inspections stateful
+
+Les familles publiques comprennent :
+
+- `inspect_solana_core_stateful_readiness` ;
+- inspections SPL Token et ATA ;
+- inspections et corrélations Token-2022 ;
+- préflight cryptographique Token-2022 ;
+- lecture et matérialisation stateful du registre ElGamal.
+
+```rust
+async fn inspect_classic_token<S>(
+    store: &S,
+    request: kb_pipeline::SplTokenStatefulReadinessRequest,
+) -> kb_core::Result<kb_pipeline::SplTokenStatefulReadinessReport>
+where
+    S: kb_store::CanonicalTransactionStore + Sync,
+{
+    let result = kb_pipeline::inspect_spl_token_stateful_readiness(store, request).await;
+
+    match result {
+        Ok(report) => Ok(report),
+        Err(error) => Err(error),
+    }
+}
+```
+
+Les rapports stateful ne constituent jamais une autorisation implicite d’exécution.
+
+## Observateurs
+
+Les campagnes longues exposent des traits d’observation distincts pour le backfill, l’extraction Core et le replay. L’observateur peut publier la progression et participer à l’annulation coopérative selon le contrat concerné.
+
+## Erreurs et invariants
+
+- toutes les campagnes sont bornées ;
+- la progression persistée ne doit avancer qu’après traitement cohérent ;
+- le replay doit rester déterministe pour une même entrée et une même version de pipeline ;
+- une matérialisation ne doit pas inventer un état confirmé ;
+- les erreurs de transport, stockage, décodage et préflight restent distinguées.
+
+## Tests de référence
+
+- tests de frontière contiguë et reprise du backfill ;
+- tests d’extraction Core et d’idempotence ;
+- tests de decode replay, dispatch et matérialisation ;
+- tests stateful SPL Token, ATA et Token-2022 ;
+- tests de preuves, préflight cryptographique et postconditions ;
+- tests du registre ElGamal fail-closed.
+
+## Limites durables
+
+- la crate orchestre les traitements mais ne fournit pas d’interface opérateur ;
+- elle ne conserve pas de secret de wallet ;
+- elle ne remplace pas les scénarios Devnet et validations explicites de `kb-pipeline-demo-scenarios`.