v0.3.9-pre.008

2026-09-05 17:39:50 +02:00
parent b0079fc3ee
commit 5c3c8b3fef
10 changed files with 145 additions and 56 deletions
--- a/docs/000-README.md
+++ b/docs/000-README.md
--- a/docs/architecture/000-README.md
+++ b/docs/architecture/000-README.md
@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/000-README.md -->
-<!-- version: 11 -->
+<!-- version: 12 -->

 # Architecture KSP

@@ -25,8 +25,8 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
 6. [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) — propriété des contrats wire, politique de dépendances codecs/interfaces, API Program ouverte, preparation d'exécution et extensibilité externe ;
 7. [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md) — policy multi-checkpoints, orchestration transactionnelle, wallet/transport, retry, approval externe et résultat d'exécution ;
 8. [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) — niveaux durables D1–D4, Materialization, Store PostgreSQL de référence, provenance, idempotence, replay et notifications de données persistées ;
-9. [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) — pipelines spécialisés, workers live, jobs de backfill/replay, backlog, claim/lease, reprise, concurrence et mécanisme de notification de référence ;
+9. [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) — séparation durable pipelines/workers/jobs, Worker API générique, producteurs RAW indépendants, reprise, concurrence et frontières de composition ;
 10. [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md) — apps spécialisées, workers autonomes et need-driven, control plane, scenarios réutilisables, demos desktop et frontières IPC/orchestration.
-11. [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md) — taxonomie durable d'acquisition `RawTransaction`, audits datés des voies Solana/providers, convergence Store et handoff Worker/Backfill.
+11. [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md) — synthèse Store-centrique des sources/capabilities `RawTransaction`, matrices providers/réseaux/preuves et handoffs indépendants Worker live / Backfill historique.

 `004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires.
--- a/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
+++ b/docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
-<!-- version: 13 -->
+<!-- version: 14 -->

 # Acquisition, workers, jobs et pipelines spécialisés

@@ -55,9 +55,7 @@ persistence D1 RAW
 notification after commit
 ```

-Une crate spécialisée `ksp-pipeline-raw-ingestion-lib` peut être introduite lorsque la réutilisation worker + job le justifie réellement.
-
-Elle ne choisit pas le provider réseau et ne pilote pas le range historique.
+La canonicalisation `RawTransaction` réutilisable entre producteurs est désormais attribuée à une lower-layer source-neutral dédiée, `ksp-raw-transaction-lib`, à matérialiser avec le Worker RAW. Elle possède uniquement la normalisation/canonicalisation commune et la construction des modèles RAW/provenance ; elle ne possède ni lifecycle Worker/Job, ni provider, ni routing réseau, ni campagne historique.

 ### `ksp-job-backfill-lib`

@@ -136,15 +134,15 @@ Une stratégie peut donc être :
 - **alternative** : une source choisie à la place d'une autre ;
 - **complémentaire** : une source découvre une signature/slot et une autre hydrate la transaction complète ;
 - **redondante** : plusieurs providers/transports observent la même transaction et produisent des observations distinctes ;
- **spécialisée** : une source live, une source de catch-up/gap repair et une source historique peuvent coexister avec des responsabilités différentes.
+- **spécialisée** : une source live, une voie d'hydration et une voie de continuité/gap repair du run peuvent coexister avec des responsabilités différentes.

 Le worker ne doit pas être réduit à un enum superficiel `Http | WebSocket | Grpc`. La configuration/runtime doit exprimer les **capacités et rôles d'acquisition réellement nécessaires** : discovery, hydration, direct full transaction, live, replay/catch-up, gap repair, filtre, finality/commitment, reprise et limites.

-#### Audit obligatoire avant `0.3.10`
+#### Résultat de l'audit `0.3.9`

-La fin de `0.3.9`, après fermeture fonctionnelle de `ksp-worker-api`, produit un audit exhaustif servant d'entrée architecturale à `0.3.10`. Cet audit ne doit pas déformer Worker API pour le premier consumer : un besoin découvert n'est remonté dans `ksp-worker-api` que s'il est réellement générique à des services continus non Solana.
+L'audit exhaustif est synthétisé dans [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md). Il confirme qu'un besoin d'acquisition Solana/provider ne remonte pas dans `ksp-worker-api` : le contrat générique reste fermé et le futur Worker concret porte ses propres capabilities de sources.

-L'audit doit au minimum comparer :
+Les familles admises par la synthèse couvrent notamment :

 ```text
 HTTP getSignaturesForAddress + getTransaction
@@ -161,7 +159,7 @@ replay/from_slot/catch-up lorsqu'une implémentation/provider le permet
 combinaisons multi-provider et multi-transport
 ```

-La liste n'est pas une promesse d'implémentation. Chaque voie est évaluée avant admission et peut être rejetée, réservée au backfill, réservée au live ou nécessiter une adaptation Transport/Config.
+La présence d'une voie dans l'architecture signifie qu'elle doit pouvoir être représentée lorsque son usage est pertinent ; son implémentation, son accessibilité commerciale et sa preuve live restent des dimensions séparées. Une même famille protocolaire peut servir au Worker, au Job ou aux deux selon l'intention, sans créer de relation entre ces producteurs.

 Pour chaque voie, l'audit couvre au minimum :

@@ -343,26 +341,24 @@ Un satellite protocolaire reste avec son groupe : Meteora vaults avec Meteora, P

 Le pattern latest-value de `ksp-job-api` peut être réutilisé conceptuellement lorsqu'il convient, mais Worker et Job conservent des sémantiques distinctes : un worker est un service continu qui peut rester actif indéfiniment, tandis qu'un job représente un traitement borné/terminable. Une dépendance `ksp-worker-api -> ksp-job-api` n'est pas supposée ; la réutilisation concrète doit être justifiée par un contrat réellement commun.

-Concepts candidats :
+Contrats communs actuels :

 ```text
 WorkerId
-WorkerDescriptor
+WorkerKindCode
 WorkerState
 WorkerHealth
-WorkerCapabilities
+WorkerActivity
+WorkerLifecycle
+WorkerStopToken
+WorkerSnapshotSequence
+WorkerSnapshot
+WorkerSnapshotSource
 ```

-Opérations minimales candidates :
+Le snapshot commun est fixe et ne porte aucun payload métier. `WorkerSnapshotSource` suit une sémantique latest-value object-safe. `WorkerStopToken` exprime une intention coopérative partagée.

-```text
-start
-stop
-status
-health
-```
-
-Une capability comme `reconfigure` n'est pas imposée à tous les workers.
+La crate n'expose aucune opération runtime universelle `start`, `stop`, `restart` ou `reconfigure`. Le Worker concret possède son runtime et traduit ses opérations de contrôle en transitions `WorkerLifecycle` et snapshots communs.

 ## Job API

@@ -458,6 +454,8 @@ Les événements utiles comprennent notamment :

 ### RAW backfill

+État actuel avant extraction de la normalisation commune :
+
 ```text
 ksp-job-backfill-lib
    -> ksp-job-api
@@ -466,15 +464,26 @@ ksp-job-backfill-lib
    -> ksp-onchain-transport-lib
    -> ksp-store-lib       # façade Store ; default-features=false côté Job
    -> futures-util/tokio  # runtime privé de Backfill
-    -> serde_json/sha2     # RAW v1 canonique + digest
+    -> serde_json/sha2     # RAW v1 canonique + digest actuellement locaux
 ```

+Cible après matérialisation de la lower-layer commune :
+
+```text
+ksp-job-backfill-lib
+    -> ksp-raw-transaction-lib
+    -> ksp-store-lib
+```
+
+Le Job conserve seul ses scopes, campagnes, checkpoints et lifecycle.
+
 ### RAW worker

 ```text
 ksp-worker-raw-transaction-ingest-lib
    -> ksp-worker-api
    -> ksp-onchain-transport-lib
+    -> ksp-raw-transaction-lib
    -> ksp-interface-lib   # seulement si un fait passif partagé aide réellement la composition live
    -> ksp-store-lib       # façade Store ; aucun backend physique direct
    -> ksp-logging-lib
@@ -486,6 +495,8 @@ composition supérieure / future Desk
    -> ksp-store-lib
 ```

+Le Worker conserve seul son runtime continu, ses sources actives, sa continuité et son lifecycle. Il n'appelle ni ne pilote le Job Backfill.
+
 Les événements Interface peuvent servir de signal provider-neutral à la composition live, mais ne constituent jamais le backlog durable. Après crash ou perte d'un événement, la reprise s'appuie sur Store et sur les primitives de replay/hydratation appropriées.

 ### CORE replay/worker
@@ -516,8 +527,6 @@ selon les capacités réellement introduites.

 ## Questions laissées ouvertes

- nom final de la crate pipeline RAW si la réutilisation worker + backfill justifie réellement une crate dédiée ;
- taxonomie exacte des stratégies/source capabilities de `ksp-worker-raw-transaction-ingest-lib`, à décider par l'audit de fin `0.3.9` ;
 - politique d'alias externe `mainnet-beta` à matérialiser uniquement aux frontières qui en ont réellement besoin, sans créer une seconde identité Store ;
 - modèle de claim/lease PostgreSQL pour les futurs processors continus ;
 - taille de batch et stratégie backpressure des workers de processing ;
--- a/docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
+++ b/docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md
@@ -1,5 +1,5 @@
 <!-- file: docs/plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md -->
-<!-- version: 16 -->
+<!-- version: 17 -->

 # Plan v0.3.9 — Worker API générique + audit RAW Transaction

@@ -632,15 +632,17 @@ Le premier gate `pre.007` a échoué sur une canary historique de `ksp-onchain-t

 #### `pre.007-fix.002` — baseline Yellowstone 12.7 + adaptation des fixtures Geyser

-**Statut : livré ; correctif dépendances/tests, revalidation opérateur requise.**
+**Statut : livré ; revalidation opérateur PASS, gate `pre.007` fermé.**

 Après `fix.001`, l'opérateur choisit explicitement les baselines workspace `jsonschema = ^0.53` et `yellowstone-grpc-proto = ^12.7`. Le check workspace confirme l'adoption de `jsonschema 0.53.0`; Yellowstone 12.7 conserve les surfaces KSP utilisées mais ajoute au service protobuf `Geyser` le RPC serveur `SubscribeGossip`, ce qui rend incomplètes les deux implémentations fixtures de `unit_tests/grpc_unary.rs` et `unit_tests/grpc_stream.rs`. Le correctif implémente uniquement l'associated stream type et `subscribe_gossip` dans ces fixtures avec réponse `UNIMPLEMENTED`, sans exposer Gossip dans l'API Transport ni ouvrir une fonctionnalité `0.3.9`. Le fixture `GetVersion` est aligné sur `12.7`. Cargo devient `0.3.9-pre.7.fix.2`.

+La revalidation opérateur du 5 septembre 2026 est PASS : audits Rust/Markdown propres, `cargo check --workspace`, Clippy workspace/all-targets/all-features `-D warnings`, 385/385 tests unitaires Transport, 43/43 canaries `release_completeness`, workspace complet `--all-targets --all-features`, Worker API complet et arbres Cargo jusqu'à `cargo tree --duplicates`. Les smokes live/operator-only restent uniquement `ignored` conformément à leur politique. `pre.007` est donc techniquement fermé.
+
 ### `pre.008` — réconciliation documentaire finale

-**Statut : prévu.**
+**Statut : livré ; gate documentaire opérateur requis.**

-Budget cible : **10-15 min**. Réconcilier README, USAGE, plan, validation et architecture avec l’état technique déjà fermé, sans nouveau runtime.
+Budget cible : **10-15 min**. La tranche passe mécaniquement Cargo à `0.3.9-pre.8` et réconcilie uniquement la documentation durable avec l'état technique fermé : README/USAGE Worker API, index documentation/architecture, séparation Worker/Job et ownership de la normalisation RAW, plan et validation. Aucun runtime, test Rust, Config, Store, Transport, CHANGELOG, ROADMAP ou prompt suivant n'est modifié.

 ### `pre.009` — préparation de publication

--- a/docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md
+++ b/docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md
@@ -1,5 +1,5 @@
 <!-- file: docs/validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md -->
-<!-- version: 15 -->
+<!-- version: 16 -->

 # Validation v0.3.9 — Worker API + audit RAW Transaction

@@ -297,18 +297,38 @@ Le gate n'est donc pas fermé : l'unique défaut est traité par `pre.007-fix.00
 - [X] Les deux fixtures implémentent le nouveau RPC avec réponse `UNIMPLEMENTED`; aucune API Gossip de production n'est ajoutée.
 - [X] Le fixture `GetVersion` est aligné sur `fixture-yellowstone-12.7`.
 - [X] `workspace.package.version = 0.3.9-pre.7.fix.2`.
- [ ] Rejouer `cargo clippy --workspace --all-targets --all-features -- -D warnings`.
- [ ] Rejouer `cargo test --workspace --all-targets --all-features`.
- [ ] Rejouer le gate Worker/API et les arbres de dépendances avant fermeture définitive de `pre.007`.
+- [X] `cargo clippy --workspace --all-targets --all-features -- -D warnings` PASS.
+- [X] `cargo test --workspace --all-targets --all-features` PASS ; smokes live/operator-only explicitement `ignored`.
+- [X] Gate Worker/API PASS et arbres `--edges normal`, `-e features`, `--duplicates` exécutés jusqu'à leur terme.
+
+### Fermeture définitive de `pre.007`
+
+Le gate opérateur final sur `0.3.9-pre.7.fix.2` est fermé :
+
+- [X] audits Rust/Markdown propres avant le gate ciblé ; Markdown 332 tables / 746 fichiers ;
+- [X] `cargo check --workspace` PASS ;
+- [X] Clippy workspace/all-targets/all-features `-D warnings` PASS ;
+- [X] `ksp-onchain-transport-lib --lib` : 385/385 PASS ;
+- [X] `ksp-onchain-transport-lib --test release_completeness` : 43/43 PASS ;
+- [X] `cargo test --workspace --all-targets --all-features` PASS ; seuls les smokes/probes explicitement opt-in restent `ignored` ;
+- [X] `cargo test -p ksp-worker-api` PASS : 32 tests au total, doc-tests sans échec ;
+- [X] graphe normal Worker : `ksp-worker-api -> ksp-core-lib` uniquement ;
+- [X] feature tree Worker : feature `default` de Core uniquement ;
+- [X] `cargo tree --duplicates` exécuté jusqu'à son terme.
+
+Aucun défaut technique ouvert ne subsiste pour `pre.007`.

 ### `pre.008` — réconciliation documentaire

- [ ] Worker API README version-neutral de surface/responsabilités.
- [ ] Worker API USAGE version-neutral avec exemples réutilisables.
- [ ] Plan/validation réconciliés sur preuves réelles.
- [ ] Architectures/index docs réconciliés.
- [ ] Audit RAW final relu comme handoff 0.3.10/0.3.12.
- [ ] Aucun CHANGELOG/ROADMAP/prompt suivant finalisé ici.
+- [X] Worker API README version-neutral réconcilié sur la surface/responsabilités finales.
+- [X] Worker API USAGE version-neutral réconcilié avec exemples réutilisables et distinction lifecycle/runtime.
+- [X] Plan/validation réconciliés sur les preuves opérateur réelles de `pre.007-fix.002`.
+- [X] Index documentation/architecture réconciliés avec le plan/validation `0.3.9`.
+- [X] `009-ACQUISITION_WORKERS_AND_JOBS.md` aligné sur la Worker API figée et sur `ksp-raw-transaction-lib` comme lower-layer commune cible.
+- [X] Audit RAW `011` relu comme handoff indépendant `0.3.10` Worker live / `0.3.12` Backfill historique ; aucune correction de contenu nécessaire.
+- [X] Aucun CHANGELOG/ROADMAP/prompt suivant finalisé ici.
+- [X] `workspace.package.version = 0.3.9-pre.8`.
+- [ ] Gate documentaire opérateur post-delta à exécuter.

 ### `pre.009` — publication

@@ -328,10 +348,10 @@ Le gate n'est donc pas fermé : l'unique défaut est traité par `pre.007-fix.00

 La livraison initiale `pre.001` avait conservé `workspace.package.version = 0.3.8` en suivant l’exception du prompt 028. Cette exception est supplantée par la règle normative `VER-ID-009`.

-Après la synthèse multi-source `pre.006`, l'état courant est :
+Après la fermeture technique `pre.007` et la réconciliation documentaire `pre.008`, l'état courant est :

 ```text
-workspace.package.version = 0.3.9-pre.6
+workspace.package.version = 0.3.9-pre.8
 ```

-`pre.002` reste la tranche non-fix `0.3.9-pre.2`. Les correctifs de conformité/compilation portent successivement `0.3.9-pre.2.fix.1` puis `0.3.9-pre.2.fix.2` conformément à `VER-ID-007` et `VER-ID-010`. `pre.003` reprend ensuite la séquence prerelease normale avec `0.3.9-pre.3`; son gate opérateur est PASS et freeze Worker API. `pre.004` poursuit avec `0.3.9-pre.4` sans changement runtime, uniquement l'audit standard Solana/KSP et la création de l'owner durable d'acquisition. `pre.005` passe à `0.3.9-pre.5` et enrichit cet owner avec l'audit Helius/Yellowstone/providers/kbot3 sans modifier le runtime. `pre.006` passe à `0.3.9-pre.6` et ferme la synthèse exhaustive possibilités/support/preuve ainsi que les handoffs `0.3.10`/`0.3.12`. `pre.006-fix.001` réécrit ensuite l'owner d'architecture comme synthèse Store-centrique et corrige la séparation Worker live / Job historique sans modifier Cargo ; `pre.006-fix.002` fixe `mainnet` comme identité canonique sans runtime. `pre.006-fix.003` matérialise finalement cette normalisation dans Config/Store/Transport/tests et porte la version Cargo `0.3.9-pre.6.fix.3`. `pre.007` ouvre ensuite le gate technique en `0.3.9-pre.7`; son premier passage révèle une canary Transport historique trop couplée au manifeste racine. `pre.007-fix.001` corrige cet ownership et porte Cargo en `0.3.9-pre.7.fix.1`. L'opérateur choisit ensuite les baselines `jsonschema ^0.53` et `yellowstone-grpc-proto ^12.7`; `pre.007-fix.002` adapte les fixtures serveur au nouveau RPC `SubscribeGossip` de Yellowstone 12.7 et porte Cargo en `0.3.9-pre.7.fix.2`. L'état précédent `0.3.9-pre.1.fix.2` reste documenté dans `pre.001-fix.002`.
+`pre.002` reste la tranche non-fix `0.3.9-pre.2`. Les correctifs de conformité/compilation portent successivement `0.3.9-pre.2.fix.1` puis `0.3.9-pre.2.fix.2` conformément à `VER-ID-007` et `VER-ID-010`. `pre.003` reprend ensuite la séquence prerelease normale avec `0.3.9-pre.3`; son gate opérateur est PASS et freeze Worker API. `pre.004` poursuit avec `0.3.9-pre.4` sans changement runtime, uniquement l'audit standard Solana/KSP et la création de l'owner durable d'acquisition. `pre.005` passe à `0.3.9-pre.5` et enrichit cet owner avec l'audit Helius/Yellowstone/providers/kbot3 sans modifier le runtime. `pre.006` passe à `0.3.9-pre.6` et ferme la synthèse exhaustive possibilités/support/preuve ainsi que les handoffs `0.3.10`/`0.3.12`. `pre.006-fix.001` réécrit ensuite l'owner d'architecture comme synthèse Store-centrique et corrige la séparation Worker live / Job historique sans modifier Cargo ; `pre.006-fix.002` fixe `mainnet` comme identité canonique sans runtime. `pre.006-fix.003` matérialise finalement cette normalisation dans Config/Store/Transport/tests et porte la version Cargo `0.3.9-pre.6.fix.3`. `pre.007` ouvre ensuite le gate technique en `0.3.9-pre.7`; son premier passage révèle une canary Transport historique trop couplée au manifeste racine. `pre.007-fix.001` corrige cet ownership et porte Cargo en `0.3.9-pre.7.fix.1`. L'opérateur choisit ensuite les baselines `jsonschema ^0.53` et `yellowstone-grpc-proto ^12.7`; `pre.007-fix.002` adapte les fixtures serveur au nouveau RPC `SubscribeGossip` de Yellowstone 12.7 et porte Cargo en `0.3.9-pre.7.fix.2`. Le gate global `pre.007` est ensuite PASS. `pre.008` porte l'état documentaire candidat à `0.3.9-pre.8`. L'état précédent `0.3.9-pre.1.fix.2` reste documenté dans `pre.001-fix.002`.