v0.3.5-pre.008-fix.001

CHANGELOG.md

@@ -1,5 +1,5 @@
 <!-- file: CHANGELOG.md -->
-<!-- version: 24 -->
+<!-- version: 25 -->
 
 # Changelog KSP
 
@@ -13,7 +13,7 @@ La frontière d'ownership reste stricte : les DTOs wire/provider demeurent dans
 
 Les gates de clôture passent audits Rust/Markdown, `cargo check --workspace`, Clippy all-targets, tests ciblés Interface/Program API, `cargo test --workspace` et graphes Cargo. `cargo tree -p ksp-interface-lib --edges normal` confirme le chemin `ksp-interface-lib -> ksp-core-lib -> solana-pubkey -> solana-address`; le graphe features ne montre aucune feature propre Interface et les doublons éventuels restent ceux du workspace global. La documentation durable a été réconciliée et `TransactionLogEvent` est conservé comme idée différée soumise à un nouveau gate consumer/bornes.
 
-`prompts/025-V0_3_6_START_PROMPT.md` ouvre `0.3.6` sur `ksp-job-api` et un premier backfill historique RAW concret. Le job doit consommer `ksp-store-lib`, conserver policy/batch-size/progression/checkpoint hors de Store et auditer en `pre.001` le premier parcours `RawTransaction` historique, avec `getSignaturesForAddress` + `getTransaction` comme candidat prioritaire plutôt que comme décision irrévocable.
+`prompts/025-V0_3_6_START_PROMPT.md` ouvre `0.3.6` sur le développement parallèle de `ksp-job-api` et `ksp-job-backfill-lib`. La release doit reprendre fonctionnellement le backfill historique kbot3 sans en copier le code : audit obligatoire de l'archive historique, `RawTransaction` par adresse via `getSignaturesForAddress` + `getTransaction`, directions/anchors et déduplication, hydratation/persistence via les façades KSP, frontier/checkpoint/reprise, cancellation/concurrency bornées, idempotence et distinctions missing/conflit. `ksp-job-api` doit en parallèle stabiliser lifecycle/progress/outcome et un contrat de notifications/listeners borné pour qu'une couche supérieure puisse visualiser l'état sans parser les logs. Le ROADMAP enchaîne ensuite l'app de backfill/inspection `0.3.7`, `ksp-worker-api` `0.3.8`, `ksp-worker-live-transactions-retriever-lib` `0.3.9` puis une application de monitoring/visualisation Jobs + Workers `0.3.10`, avec reprise du même pattern d'observabilité côté Worker sans fusionner les sémantiques Job/Worker/Store.
 
 ## 0.3.4 — Store/PostgreSQL RawAccountState + complétude RAW — 2026-08-31
 

ROADMAP.md

@@ -1,5 +1,5 @@
 <!-- file: ROADMAP.md -->
-<!-- version: 99 -->
+<!-- version: 100 -->
 
 # Roadmap KSP
 
@@ -98,9 +98,11 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
 - [X] `0.3.3` — Vertical slice PostgreSQL `RawTransaction` complète sur `ksp-store-lib` + `ksp-store-postgres-lib` : six capabilities transaction/observation/rétention, V001 physique liée à un réseau, acquisition canonical+observation atomique, idempotence/conflit, get/list keyset cursorisé, archive/purge/tombstone/ForceRehydrate, hardening des erreurs et du schéma, concurrence et rollback validés sur PostgreSQL 17.
 - [X] `0.3.4` — Vertical slice PostgreSQL `RawAccountState` complète sur `ksp-store-lib` + `ksp-store-postgres-lib` : quatre capabilities account ajoutées aux six transaction pour une conformance RAW 10/10, V002 additive de 32 ressources au-dessus de V000/V001 immuables, state+observation atomiques, idempotence/conflit exacts, metadata Yellowstone observation-only, get/list keyset `(slot,pubkey,state_hash)` avec cursor KSPA anti-replay, hardening cross-family et live validé sur PostgreSQL 17 sans rétention destructive account.
 - [X] `0.3.5` — `ksp-interface-lib` étendu avec deux familles passives réellement partagées : `SlotLifecycleEvent` (`Processed`, `FirstShredReceived`, `Completed`, `CreatedBank`, `Dead`, `OptimisticallyConfirmed`, `Rooted`) et `TransactionExecutionEvent` (`slot + TransactionSignature[64] + Succeeded/Failed`). Interface reste Core-only, provider-neutral, sans serde/codec/runtime/event bus et sans duplication de `RawTransaction`/`RawAccountState`; les DTOs riches restent Transport-owned et les candidats non convergents restent différés.
-- [ ] `0.3.6` — Introduire `ksp-job-api` et un premier job de backfill historique RAW concret consommant `ksp-store-lib`; auditer en priorité un backfill `RawTransaction` par adresse via pagination Transport, avec policy/batch-size/progression/checkpoint/cancellation possédés par le job et jamais par Store.
+- [ ] `0.3.6` — Introduire en parallèle `ksp-job-api` et `ksp-job-backfill-lib` : reprendre fonctionnellement le backfill historique kbot3 sur les abstractions KSP actuelles (`ksp-onchain-transport-lib` + `ksp-store-lib`), fermer une première verticale `RawTransaction` historique par adresse avec directions/anchors, déduplication, hydratation, idempotence, frontier/checkpoint/reprise, cancellation et concurrency bornées, et stabiliser un lifecycle/progress/outcome avec notifications/listeners sûrs pour les couches supérieures.
-- [ ] `0.3.7` — Introduire une application spécialisée de backfill/inspection RAW.
+- [ ] `0.3.7` — Introduire une application spécialisée de backfill/inspection RAW consommant `ksp-job-api` : lancement/annulation contrôlés, état et progression live, compteurs, checkpoint/frontière, outcome terminal et inspection RAW sans parser les logs ni connaître les providers/backends physiques.
-- [ ] Compléter ensuite la couche RAW avec le worker/service live, son contrôle et les outils d’exploitation réellement nécessaires avant de passer à la couche de normalisation générique suivante.
+- [ ] `0.3.8` — Introduire `ksp-worker-api` comme API générique de lifecycle/health/progression pour services continus, en reprenant le pattern de notifications/listeners stabilisé par Job tout en gardant les sémantiques Worker distinctes des jobs terminables et des wake-ups Store post-commit.
+- [ ] `0.3.9` — Introduire `ksp-worker-live-transactions-retriever-lib` pour l'acquisition continue `RawTransaction` via les surfaces live de `ksp-onchain-transport-lib`, persistence par `ksp-store-lib`, reprise/backpressure/idempotence et notifications `ksp-worker-api`, sans decode Program ni dépendance backend/provider directe.
+- [ ] `0.3.10` — Introduire une application de monitoring/visualisation Jobs + Workers : vue graphique des lifecycles, health/progression, rates/backpressure/retries sûrs, checkpoints et outcomes ; l'application consomme les APIs publiques Job/Worker et ne devient ni scheduler caché ni source de vérité du backlog.
 
 ### TODO/IDEAS — taxonomie N1, processing et rétention
 

deltas/0.3.5/pre.008-fix.001.md

@@ -0,0 +1,177 @@
+<!-- file: deltas/0.3.5/pre.008-fix.001.md -->
+<!-- version: 1 -->
+
+# Delta `0.3.5-pre.008-fix.001` — enrichissement du prompt `0.3.6` et trajectoire Job/Worker
+
+## Base requise
+
+```text
+0.3.5-pre.008
+workspace.package.version = 0.3.5-pre.8
+```
+
+Ce fix est **strictement documentaire**. Il ne modifie aucun fichier Rust/build/runtime/config et ne change donc pas `workspace.package.version`.
+
+`Cargo.toml` reste exactement celui de `pre.008` :
+
+```text
+workspace.package.version = 0.3.5-pre.8
+```
+
+## Motif du fix
+
+Le prompt `025` de `pre.008` était insuffisamment détaillé par rapport :
+
+- aux règles de construction des prompts KSP ;
+- à la portée réelle attendue de `0.3.6` ;
+- aux fonctionnalités de backfill déjà présentes historiquement dans kbot3 ;
+- au besoin d'observabilité par une couche supérieure ;
+- à la trajectoire Worker qui doit reprendre le même pattern de notifications.
+
+Il laissait également le nom de la crate concrète à décider alors que la direction est désormais fixée :
+
+```text
+ksp-job-backfill-lib
+```
+
+## Corrections du prompt `0.3.6`
+
+Le prompt version 2 ouvre désormais explicitement :
+
+```text
+ksp-job-api
++
+ksp-job-backfill-lib
++
+backfill RawTransaction historique fonctionnel
++
+lifecycle/progression/outcome
++
+notifications/listeners sûrs pour UI/composition
+```
+
+### Archive kbot3
+
+L'archive :
+
+```text
+khadhroony-bot3_v0.5.3-pre.005-fix010.zip
+```
+
+redevient **obligatoire en `0.3.6-pre.001`**, mais uniquement comme inventaire fonctionnel historique.
+
+Le plan doit construire une matrice :
+
+```text
+REPRENDRE FONCTIONNELLEMENT
+REDESSINER POUR KSP
+REPORTER
+REJETER
+```
+
+Le code, les anciennes crates, DTOs, SQL, retries et choix runtime kbot3 ne sont pas à copier.
+
+### Parité fonctionnelle minimale à réauditer
+
+Le prompt rend explicites les invariants historiquement démontrés :
+
+- scans latest/before/after/explicit selon audit ;
+- anchors et directions ;
+- candidats/pages dédupliqués ;
+- nearest-newer/gap-fill si conservé ;
+- frontier de complétion contiguë ;
+- reprise après cancellation sans saut ;
+- cancellation coopérative pendant RPC long et wait/backoff ;
+- ownership séparé du retry Transport et du retry Job ;
+- compteurs de campagne distinguant sélection, complétion, insert/idempotence/existing, missing et observations.
+
+### Notifications Job
+
+Le prompt exige désormais un vrai contrat d'observabilité `ksp-job-api` :
+
+```text
+identity
+state/phase
+progress/snapshot
+checkpoint/frontier
+sequence ou ordre observable
+terminal outcome
+safe error code
+listener isolation/backpressure
+resynchronisation après perte/coalescing
+```
+
+Ces notifications sont explicitement distinctes :
+
+```text
+Interface acquisition events
+Store KSP-NOTIFY-* post-commit wake-ups
+logging/tracing
+```
+
+Aucune dépendance Tokio/channel précise n'est imposée dans `ksp-job-api` avant l'audit `pre.001`.
+
+### Alignement Worker futur
+
+Le même pattern conceptuel devra être repris par `ksp-worker-api`, sans créer dès `0.3.6` une crate générique spéculative supplémentaire.
+
+## Corrections du ROADMAP
+
+La trajectoire RAW opérationnelle devient explicitement :
+
+```text
+0.3.6  ksp-job-api + ksp-job-backfill-lib + notifications
+0.3.7  application backfill/inspection RAW
+0.3.8  ksp-worker-api
+0.3.9  ksp-worker-live-transactions-retriever-lib
+0.3.10 application monitoring/visualisation Jobs + Workers
+```
+
+L'ancien placeholder générique « worker/service live ensuite » est supprimé au profit de releases nommées et ordonnées.
+
+## Correction du CHANGELOG
+
+Le paragraphe ouvrant `0.3.6` est aligné sur la portée réelle du prompt version 2 et sur la nouvelle trajectoire ROADMAP.
+
+Aucune information sur le contenu fonctionnel déjà stabilisé de `0.3.5` n'est changée.
+
+## Versions d'en-tête
+
+```text
+CHANGELOG.md                                  24 -> 25
+ROADMAP.md                                    99 -> 100
+prompts/025-V0_3_6_START_PROMPT.md             1 -> 2
+deltas/0.3.5/pre.008-fix.001.md                nouveau -> 1
+```
+
+## Fichiers modifiés
+
+Exactement :
+
+```text
+CHANGELOG.md
+ROADMAP.md
+prompts/025-V0_3_6_START_PROMPT.md
+deltas/0.3.5/pre.008-fix.001.md
+```
+
+Explicitement inchangés :
+
+```text
+Cargo.toml
+crates/**
+docs/architecture/**
+docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md
+docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md
+```
+
+## Gate demandé
+
+Le fix ne modifie aucun Rust. Le gate minimal est :
+
+```bash
+python3 scripts/audit_rust_workspace_rules.py
+python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.5
+```
+
+Aucun rerun Cargo n'est requis par ce fix documentaire lui-même.