Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.3.16-pre.009

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-22 08:59:09 +02:00
parent f2227dce21
commit 40add02ac2
16 changed files with 498 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 74 -->
<!-- version: 75 -->
# Documentation KSP
@@ -133,7 +133,7 @@ Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/
La candidate `0.3.9 — Worker API générique + audit RAW Transaction` est réconciliée dans [`plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md`](plans/030-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT_PLAN.md) avec [`validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md`](validation/026-V0_3_9_WORKER_API_RAW_TRANSACTION_AUDIT.md). `ksp-worker-api` reste Core-only et runtime-neutral pour les services continus ; l'architecture RAW place Store/`RawTransaction` au centre et sépare strictement le Job Backfill historique paramétré du futur Worker Ingest continu start/stop. [`../crates/ksp-worker-api/README.md`](../crates/ksp-worker-api/README.md), [`../crates/ksp-worker-api/USAGE.md`](../crates/ksp-worker-api/USAGE.md), [`architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) et [`architecture/011-RAW_TRANSACTION_ACQUISITION.md`](architecture/011-RAW_TRANSACTION_ACQUISITION.md) constituent les références durables avant la lane de publication.
Les candidates `0.3.10` à `0.3.15` prolongent cette trajectoire RAW dans [`plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md`](plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md), [`plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md`](plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md), [`plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md`](plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md), [`plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md`](plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md), [`plans/035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md`](plans/035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md) et [`plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md`](plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md), avec leurs matrices [`validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md`](validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md) à [`validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md`](validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md). Cette séquence matérialise le Common RAW partagé, la fondation Worker, Yellowstone live, cinq familles multi-source, la continuité/gap repair puis le Desk multi-route ; `0.3.15` ferme en plus les anomalies Mainnet observées de convergence `logMessages`, backpressure Yellowstone soutenue et shutdown post-half-close. Le handoff [`plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md`](plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md) réserve explicitement à `0.3.16` les variantes RAW durables, la résolution des conflits, les retries Store/Transport et les vues correspondantes de Store Desk ; `0.3.17` et `0.3.18` portent ensuite le Backfill multi-route et son Desk adapté.
Les candidates `0.3.10` à `0.3.15` prolongent cette trajectoire RAW dans [`plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md`](plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md), [`plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md`](plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md), [`plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md`](plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md), [`plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md`](plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md), [`plans/035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md`](plans/035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md) et [`plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md`](plans/036-V0_3_15_RAW_TRANSACTION_INGEST_DESK_PLAN.md), avec leurs matrices [`validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md`](validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md) à [`validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md`](validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md). Cette séquence matérialise le Common RAW partagé, la fondation Worker, Yellowstone live, cinq familles multi-source, la continuité/gap repair puis le Desk multi-route ; `0.3.15` ferme en plus les anomalies Mainnet observées de convergence `logMessages`, backpressure Yellowstone soutenue et shutdown post-half-close. Le handoff historique [`plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md`](plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md) est supersédé pour le sizing par [`plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md`](plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md) et [`validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md`](validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md) : `0.3.16` ferme les fondations RAW multi-variantes, le sélecteur/promotion canonique, le conflit durable minimal et l'ingestion Worker non terminale ; `0.3.17` porte la résilience opérationnelle et le cycle de vie complet des variantes, `0.3.18` l'inspection/résolution Store Desk, puis les extensions Backfill multi-route et Backfill Desk sont reportées par défaut à `0.3.19` et `0.3.20`.
## Spécifications de formats

82
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 43 -->
<!-- version: 44 -->
# Inventaire initial des composants KSP
@@ -18,46 +18,46 @@ Ce document maintient l'inventaire synthétique des composants retenus ou presse
## Inventaire synthétique
| Domaine | Composant | Type | Statut | Première cible actuelle | Mission |
|-------------------------|-----------------------------------------|-------------|--------------|----------------------------------|------------------------------------------------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales |
| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP |
| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config |
| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config |
| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Stable | `0.2.1`–`0.2.4` | HTTP standard complet : 52/52 current + 14/14 historical |
| Wallet | `ksp-wallet-lib` | lib | Stable | `0.2.5` | `.kspwallet`, VIEW/OWNER, secrets, signature, import/export |
| Wallet Desk | `ksp-app-wallet-desk` | app | Stable | `0.2.6` | Wallet + Config + balance HTTP + projection SOL/USD auxiliaire |
| Wallet V2 | `ksp-wallet-lib` | lib | Stable | `0.2.6` | wire/runtime V2 + API default/versionnée + migration explicite |
| Standard WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.7` | WebSocket Solana 18/18, sessions/subscriptions bornées |
| Helius WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.8` | LaserStream WS : 7 standard + transaction, actor partagé |
| Yellowstone | `ksp-onchain-transport-lib` | lib | Stable | `0.2.9` | client gRPC standard/provider-neutral |
| Off-chain price | `ksp-offchain-transport-lib` | lib | Stable | `0.2.11` | prix SOL/USD multi-provider, limits et availability |
| SOL Prices Desk | `ksp-app-solprices-desk` | app | Stable | `0.2.12` | HID provider-agnostic pour visualisation/refresh prix |
| Interface passive | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire + contrats passifs partagés, dont événements acquisition provider-neutral |
| Program API | `ksp-program-api` | API | Stable | `0.2.14` | contrats extensibles Program |
| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles |
| Program extension | `ksp-program-<name>-lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` |
| Store API | `ksp-store-api` | API | Stable | `0.3.1`, extension `0.3.16` | RAW transaction/account, observations ; variantes/conflits/résolutions ajoutés sans backend leak |
| Store runtime | `ksp-store-lib` | lib | Stable | `0.3.2`–`0.3.4`, `0.3.16` | façade backend-neutral ; convergence, retry et résolution RAW partagés entre producteurs |
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4`, `0.3.16` | backend référence ; variantes conflictuelles et historique de résolution atomiques en `0.3.16` |
| Job lifecycle | `ksp-job-api` | API | Implémenté | `0.3.6` | identité/lifecycle/annulation/notifications latest-value runtime-neutral |
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6`, extension `0.3.17` | première verticale HTTP puis extension multi-route/historique sur convergence Store partagée |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7`, extension `0.3.18` | contrôle du backfill RAW ; sélection/supervision multi-route adaptée au Job `0.3.17` |
| Store Desk | `ksp-app-store-desk` | app | Implémenté | `0.3.8`, extension `0.3.16` | inspection RAW + vues conflits/variantes/historique et résolution manuelle réversible |
| RAW transaction common | `ksp-raw-transaction-lib` | lib | Implémenté | `0.3.10` | canonicalisation/wire RAW Transaction v1 source-neutral partagé entre producteurs |
| Worker lifecycle | `ksp-worker-api` | API | Implémenté | `0.3.9` | lifecycle/health/progression génériques des services continus |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Implémenté | `0.3.11`–`0.3.15`, ext. `0.3.16` | live cinq familles, continuité/repair et backpressure bornée ; conflits durables étendus en `0.3.16` |
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Implémenté | `0.3.15` | composition réseau-centrique et supervision simultanée de plusieurs routes live |
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche STRUCTURAL | normalisation Solana générique RAW -> STRUCTURAL bornée/rejouable |
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche STRUCTURAL | backlog RAW -> STRUCTURAL continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODED | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODED | implementations officielles communes |
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun |
| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC |
| Trading Intelligence | noms à définir | libs/jobs | Pressenti | après données stables | features/signaux/anomalies/ML |
| Domaine | Composant | Type | Statut | Première cible actuelle | Mission |
|-------------------------|-----------------------------------------|-------------|--------------|---------------------------------|-------------------------------------------------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | Stable | `0.1.1` | Error/Result, Program IDs et primitives fondamentales |
| Logging | `ksp-logging-lib` | lib | Stable | `0.1.2` | façade unique tracing KSP |
| Config | `ksp-config-lib` | lib | Stable | `0.1.3` | documents, profils, env et persistence Config |
| Config Desk | `ksp-app-config-desk` | app | Stable | `0.1.4` | validation/management Config |
| On-chain HTTP | `ksp-onchain-transport-lib` | lib | Stable | `0.2.1`–`0.2.4` | HTTP standard complet : 52/52 current + 14/14 historical |
| Wallet | `ksp-wallet-lib` | lib | Stable | `0.2.5` | `.kspwallet`, VIEW/OWNER, secrets, signature, import/export |
| Wallet Desk | `ksp-app-wallet-desk` | app | Stable | `0.2.6` | Wallet + Config + balance HTTP + projection SOL/USD auxiliaire |
| Wallet V2 | `ksp-wallet-lib` | lib | Stable | `0.2.6` | wire/runtime V2 + API default/versionnée + migration explicite |
| Standard WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.7` | WebSocket Solana 18/18, sessions/subscriptions bornées |
| Helius WS | `ksp-onchain-transport-lib` | lib | Stable | `0.2.8` | LaserStream WS : 7 standard + transaction, actor partagé |
| Yellowstone | `ksp-onchain-transport-lib` | lib | Stable | `0.2.9` | client gRPC standard/provider-neutral |
| Off-chain price | `ksp-offchain-transport-lib` | lib | Stable | `0.2.11` | prix SOL/USD multi-provider, limits et availability |
| SOL Prices Desk | `ksp-app-solprices-desk` | app | Stable | `0.2.12` | HID provider-agnostic pour visualisation/refresh prix |
| Interface passive | `ksp-interface-lib` | lib | Stable | `0.2.13` | façade wire + contrats passifs partagés, dont événements acquisition provider-neutral |
| Program API | `ksp-program-api` | API | Stable | `0.2.14` | contrats extensibles Program |
| Program impl. | `ksp-program-lib` | lib | Retenu | vertical slices ultérieurs | implementations Program officielles |
| Program extension | `ksp-program-<name>-lib` | lib externe | À la demande | dès besoin | implementation externe de `ksp-program-api` |
| Store API | `ksp-store-api` | API | Stable | `0.3.1`, ext. `0.3.16`/`0.3.17` | RAW transaction/account, observations ; variantes/comparateur en `0.3.16`, résolution en `0.3.17` |
| Store runtime | `ksp-store-lib` | lib | Stable | `0.3.2`–`0.3.4`, ext. `0.3.16` | façade backend-neutral ; outcomes variantes partagés, inspection/résolution étendues en `0.3.17` |
| Store PostgreSQL | `ksp-store-postgres-lib` | lib | Stable | `0.3.2`–`0.3.4`, ext. `0.3.16` | backend référence ; V003 variantes/selector/conflit minimal atomiques, lifecycle complet en `0.3.17` |
| Job lifecycle | `ksp-job-api` | API | Implémenté | `0.3.6` | identité/lifecycle/annulation/notifications latest-value runtime-neutral |
| Backfill | `ksp-job-backfill-lib` | lib | Implémenté | `0.3.6`, cible ext. `0.3.19` | première verticale HTTP ; compatibilité variantes `0.3.16`, extension multi-route/historique reportée |
| Backfill Desk | `ksp-app-backfill-desk` | app | Implémenté | `0.3.7`, cible ext. `0.3.20` | contrôle du backfill RAW ; adaptation multi-route reportée après le programme résilience/Store Desk |
| Store Desk | `ksp-app-store-desk` | app | Implémenté | `0.3.8`, extension `0.3.18` | inspection RAW actuelle ; variantes/conflits/résolutions opérateur ajoutés après contrats `0.3.17` |
| RAW transaction common | `ksp-raw-transaction-lib` | lib | Implémenté | `0.3.10` | canonicalisation/wire RAW Transaction v1 source-neutral partagé entre producteurs |
| Worker lifecycle | `ksp-worker-api` | API | Implémenté | `0.3.9` | lifecycle/health/progression génériques des services continus |
| RAW transaction worker | `ksp-worker-raw-transaction-ingest-lib` | worker/lib | Implémenté | `0.3.11`–`0.3.16` | live multi-source borné ; Store arbitre les variantes, conflit durable non terminal en `0.3.16` |
| RAW ingest Desk | `ksp-app-raw-transaction-ingest-desk` | app | Implémenté | `0.3.15` | composition réseau-centrique et supervision simultanée de plusieurs routes live |
| STRUCTURAL job | nom à fixer | job/lib | Retenu | couche STRUCTURAL | normalisation Solana générique RAW -> STRUCTURAL bornée/rejouable |
| STRUCTURAL worker | nom à fixer | worker/lib | Retenu | fin couche STRUCTURAL | backlog RAW -> STRUCTURAL continu |
| Materializer API | `ksp-materializer-api` | API | Retenu | premier groupe DECODED | contrats extensibles matérialisation |
| Materializer impl. | `ksp-materializer-lib` | lib | Retenu | premier groupe DECODED | implementations officielles communes |
| Execution policy | `ksp-execution-policy-api` | API | Retenu | premier vrai besoin execution | décision/safety multi-contexte |
| Execution orchestration | `ksp-execution-lib` | lib | Retenu | premier vrai cycle execution | Program + policy + Wallet + transport |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | Retenu | vertical slices | validation métier/devnet par groupe |
| Scenario API | `ksp-scenario-api` | API | Non retenu | — | norme souple avant trait commun |
| Market Desk | `ksp-app-market-desk` | app | Pressenti | après Meteora/Raydium/Pump/Orca | tokens, pools, trades, liquidity, price, OHLC |
| Trading Intelligence | noms à définir | libs/jobs | Pressenti | après données stables | features/signaux/anomalies/ML |
## Contrats séparés retenus

6
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
<!-- version: 22 -->
<!-- version: 23 -->
# Acquisition, workers, jobs et pipelines spécialisés
@@ -90,7 +90,7 @@ Le job :
Le caller desktop spécialisé actuel est `ksp-app-backfill-desk`. Il compose Config, le pool HTTP et Store, puis remet ces ressources au runtime Backfill. Il peut retenir le checkpoint terminal uniquement en mémoire Rust pour un Resume in-session ; cette rétention applicative ne transforme pas le checkpoint en garantie de reprise durable après redémarrage.
Cette verticale `0.3.6`/`0.3.7` est **la première stratégie de backfill**, pas la définition générale du backfill KSP. Son discovery `getSignaturesForAddress` + hydration `getTransaction` est HTTP parce que cette méthode a été choisie pour le premier vertical slice. Après stabilisation du worker live et de sa Desk, `0.3.16` ferme d'abord la résilience RAW partagée : divergences compatibles, variantes conflictuelles durables, résolution/restauration canonique, retry Store et reconnexion Transport. `0.3.17` réaudite ensuite `ksp-job-backfill-lib` pour intégrer les autres stratégies historiques/catch-up pertinentes identifiées par l'audit RAW Transaction de `0.3.9`, puis `0.3.18` adapte `ksp-app-backfill-desk` au Job multi-route.
Cette verticale `0.3.6`/`0.3.7` est **la première stratégie de backfill**, pas la définition générale du backfill KSP. Son discovery `getSignaturesForAddress` + hydration `getTransaction` est HTTP parce que cette méthode a été choisie pour le premier vertical slice. Après stabilisation du worker live et de sa Desk, `0.3.16` ferme les fondations RAW multi-variantes et le conflit durable non terminal ; `0.3.17` complète le cycle de vie/résolution des variantes ainsi que la résilience Store/Transport, puis `0.3.18` expose ces contrats dans Store Desk. L'extension multi-route/multi-stratégie de `ksp-job-backfill-lib` est reportée par défaut à `0.3.19`, et l'adaptation correspondante de `ksp-app-backfill-desk` à `0.3.20`.
### Worker RAW Transaction live
@@ -465,7 +465,7 @@ ksp-job-backfill-lib
-> serde_json/sha2 # discovery/checkpoint/observation propres au Job
```
Le Job conserve seul ses scopes, campagnes, checkpoints et lifecycle. La canonicalisation transactionnelle partagée appartient désormais à `ksp-raw-transaction-lib`; `0.3.17` étendra les stratégies historiques sans déplacer ce rôle.
Le Job conserve seul ses scopes, campagnes, checkpoints et lifecycle. La canonicalisation transactionnelle partagée appartient désormais à `ksp-raw-transaction-lib`; l'extension multi-route/historique planifiée à partir de `0.3.19` ne déplacera pas ce rôle.
### RAW worker

47
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md -->
<!-- version: 18 -->
<!-- version: 19 -->
# Acquisition et alimentation `RawTransaction`
@@ -840,16 +840,18 @@ Stop Yellowstone post-half-close : status distant tardif classé Closed, status
compatibilité étroite : canonique complet + incoming logMessages avec marqueur exact Log truncated
```
Reste hors de cette verticale et nécessite une tranche dédiée :
Après fermeture technique de `0.3.16`, restent hors de cette verticale et nécessitent des versions dédiées :
```text
sources EARLY / pre-execution
campagne historique multi-source ou caller-paramétrable
variantes RAW durables et résolution générale des conflits
promotion canonique d'une représentation moins complète vers une plus complète
retry Store et reconnexion Transport configurables au niveau prévu par 0.3.16
cycle de vie complet des conflits : résolution/reopen/historique/rétention des variantes
retry Store et reconnexion Transport configurables
Store Desk conflits/variantes/résolutions opérateur
```
Les variantes RAW durables, la promotion canonique strictement prouvée et le conflit durable minimal non terminal sont, eux, acquis par `0.3.16`.
### 14.3 Gaps Transport Worker
| ID | Adaptation | Motif |
@@ -882,9 +884,9 @@ La règle générale reste fail-closed : une divergence canonique non reconnue p
Le sens inverse reste volontairement non résolu en `0.3.15` : un canonique tronqué suivi d'une représentation complète n'est pas promu automatiquement. Deux contenus complets divergents, un préfixe incompatible, une différence hors `logMessages` ou toute relation de troncature non prouvée restent des conflits. Cette asymétrie est précisément le point d'entrée du modèle de variantes/promotion/résolution de `0.3.16`.
## 14.5 Handoff `0.3.16` : résilience RAW et conflits durables
## 14.5 Résultat `0.3.16` : fondations multi-variantes et conflits durables
`0.3.16` doit déplacer la résolution des divergences RAW dans le contrat Store partagé, afin que Worker live et futurs Jobs historiques convergent avec la même politique. Une divergence de contenu n'est plus assimilée automatiquement à une panne d'acquisition.
`0.3.16` déplace l'arbitrage durable des divergences RAW dans le contrat Store partagé, afin que Worker live et Jobs historiques utilisent la même politique de convergence. Une divergence conservable n'est plus assimilée automatiquement à une panne d'acquisition.
Modèle cible :
@@ -897,17 +899,17 @@ RawTransaction identity (network, signature)
-> historique immutable des promotions/résolutions
```
Classification minimale : `Exact`, `CompatibleLessComplete`, `CompatibleMoreComplete`, `Conflict`. Une représentation prouvée moins complète ne remplace jamais le canonique ; une représentation prouvée plus complète peut le promouvoir atomiquement ; un vrai conflit conserve toutes les variantes sans arrêter l'acquisition. La provenance d'un provider n'établit jamais à elle seule une priorité canonique.
Classification livrée : `Exact`, `CompatibleLessComplete`, `CompatibleMoreComplete`, `Conflict`, `Incomparable`. Une représentation prouvée moins complète ne remplace jamais le canonique ; une représentation prouvée plus complète le promeut atomiquement ; `Conflict` et `Incomparable` conservent la variante entrante et ouvrent/mettent à jour un conflict case minimal sans arrêter l'acquisition. La provenance d'un provider n'établit jamais à elle seule une priorité canonique.
Le Worker doit distinguer les problèmes locaux durablement gérables des pannes externes. Un conflit RAW quarantiné laisse la route active et rend la santé au plus `Degraded`. Une indisponibilité Store impose backpressure/pause et retry sans perte silencieuse. Une indisponibilité Transport déclenche une politique de reconnexion bornée/configurable (`initial_delay`, `max_delay`, backoff, `max_attempts`, reset après stabilité). Un terminal `Faulted` reste réservé aux erreurs irréconciliables ou à l'épuisement explicite d'une politique de retry/reconnect.
Le Worker distingue désormais le conflit durable d'une panne externe : `QuarantinedConflict` laisse la route `Running` et projette `Degraded`, tandis qu'un ancien backend qui renvoie encore `ERROR_CODE_RAW_CONFLICT` reste traité comme erreur terminale de compatibilité. Les politiques complètes de retry Store/backpressure `Blocked` et de reconnexion Transport configurable sont reportées à `0.3.17` ; elles ne sont pas implicitement revendiquées par `0.3.16`.
`ksp-app-store-desk` doit ajouter des vues de conflits/variantes et d'historique. Une résolution manuelle peut promouvoir une variante, conserver le canonique, ou produire une variante de fusion assistée. Toute ancienne valeur canonique reste une variante durable et peut être restaurée ultérieurement ; aucun `UPDATE` destructif ne doit rendre une décision manuelle irréversible.
`ksp-app-store-desk` reste inchangé en `0.3.16`. Les contrats d'inspection/résolution complets sont préparés en `0.3.17`, puis les vues/actions opérateur de variantes, conflits et historique sont prévues pour `0.3.18`. Toute future décision manuelle doit rester réversible et ne jamais détruire les variantes nécessaires au rollback.
Le détail de handoff est fixé dans `docs/plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md`.
Le handoff historique est conservé dans `docs/plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md`; le sizing et la répartition actuels sont fixés par `docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md`.
## 15. Handoff `0.3.17` : Job Backfill multi-stratégie
## 15. Handoff `0.3.17` -> `0.3.20`
Le Job doit conserver son vertical slice existant puis ajouter des stratégies historiques choisies selon requête + capabilities + configuration.
`0.3.17` ferme le cycle de vie complet des variantes/conflits et la résilience opérationnelle Store/Transport. `0.3.18` expose ensuite inspection et résolution dans Store Desk. Le Job Backfill multi-stratégie est reporté par défaut à `0.3.19` : il doit conserver son vertical slice existant puis ajouter des stratégies historiques choisies selon requête + capabilities + configuration. L'adaptation Backfill Desk correspondante est ciblée par défaut sur `0.3.20`.
| Stratégie | Entrée de campagne typique | Acquisition | Admission |
|----------------------------------------|-----------------------------------|----------------------------|------------------|
@@ -939,11 +941,12 @@ Ordre conseillé :
0.3.14 P0 : gaps run-local, coverage prouvée, repair borné, source-loss et shutdown/fairness cross-layer
0.3.15 P0 : Raw Transaction Ingest Desk multi-route + stabilité Mainnet Yellowstone/getBlock/polling
0.3.15 P1 : diagnostic/convergence logMessages tronqués + backpressure gRPC soutenue + Stop post-half-close
0.3.16 P0 : variantes/conflits RAW durables, promotions/résolutions, retries et Store Desk conflicts
0.3.17 P0 : block scan historique
0.3.17 P0 : replay Yellowstone borné
0.3.17 P1 : provider history/archive
0.3.17 P1 : Old Faithful
0.3.16 P0 : variantes RAW durables, promotion prouvée, conflit minimal durable, Worker non terminal
0.3.17 P0 : résolution/rétention des variantes + retry Store + reconnect Transport configurable
0.3.18 P0 : Store Desk conflits/variantes/résolutions opérateur
0.3.19 P0 : block scan historique + replay Yellowstone borné
0.3.19 P1 : provider history/archive + Old Faithful
0.3.20 P0 : Backfill Desk multi-route
plus tard : substrats directs et sources vendor-specific sans accès actuel
```
@@ -1065,9 +1068,11 @@ TR-C2 = adapter productif Transport DTO -> common réserv
0.3.11 = fondation Worker source-neutral, persistence et observabilité
0.3.12 = première verticale Yellowstone + hydration/replay continuity
0.3.13 = cinq familles live + convergence/fairness/health/shutdown/completeness
0.3.16 = résilience RAW, variantes/conflits/résolutions, retry/reconnect et Store Desk
0.3.17 = Job Backfill multi-route/multi-stratégie historique
0.3.18 = Backfill Desk multi-route
0.3.16 = fondations RAW multi-variantes + conflit durable minimal + Worker non terminal
0.3.17 = lifecycle/résolution/rétention variantes + retry Store + reconnect Transport
0.3.18 = Store Desk variantes/conflits/résolutions
0.3.19 cible = Job Backfill multi-route/multi-stratégie historique
0.3.20 cible = Backfill Desk multi-route
```
`0.3.9` n'implémente aucune nouvelle stratégie d'acquisition. Il ferme l'architecture et l'inventaire nécessaires aux releases suivantes.

36
docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Plan `0.3.16` -> `0.3.18` — résilience RAW, variantes, conflits et récupération
@@ -978,19 +978,19 @@ Backend PostgreSQL : bootstrap V003, variant ledger, rattachement exact des nouv
#### `0.3.16-pre.005`
Comparateur partagé : `Exact`, `CompatibleLessComplete`, `CompatibleMoreComplete`, `Conflict`, `Incomparable` ; canaris `logMessages` bidirectionnels et politique fail-closed sur les autres champs. Implémentation livrée par cette tranche ; gate opérateur requis avant `pre.006`.
Comparateur partagé : `Exact`, `CompatibleLessComplete`, `CompatibleMoreComplete`, `Conflict`, `Incomparable` ; canaris `logMessages` bidirectionnels et politique fail-closed sur les autres champs. Implémentation livrée et gate opérateur confirmé propre après `pre.005-fix.001`.
#### `0.3.16-pre.006`
Sélecteur canonique et promotion atomique : revision, projection V001 cohérente, conservation de l'ancien canonique et journal minimal des transitions.
Sélecteur canonique et promotion atomique : revision, projection V001 cohérente et conservation de l'ancien canonique. Implémentation livrée et gate opérateur confirmé propre après `pre.006-fix.001`.
#### `0.3.16-pre.007`
Conflit durable minimal + intégration Worker : variante conservée, case ouverte, outcome non terminal, suppression/restriction de l'arbitrage run-local plus fort que le Store et health `Degraded` lorsque requis.
Conflit durable minimal + intégration Worker : variante conservée, case ouverte, outcome non terminal, suppression de l'arbitrage run-local plus fort que le Store et health `Degraded`. Implémentation livrée et gate opérateur confirmé entièrement propre après `pre.007-fix.003`.
#### `0.3.16-pre.008`
Hardening technique ciblé de la vertical slice : concurrence, rollback transactionnel, régressions Store/Job Backfill/Worker, preuves PostgreSQL live opt-in actualisées et gate workspace. Cette tranche ne mélange ni réconciliation documentaire durable ni préparation de publication.
Hardening technique ciblé de la vertical slice : concurrence, rollback transactionnel, régressions Store/Job Backfill/Worker, preuve PostgreSQL live opt-in et gate workspace. Le live RawTransaction a été exécuté avec succès sur PostgreSQL 17 ; le gate opérateur est entièrement propre après `pre.008-fix.001`.
#### `0.3.16-pre.009`
@@ -1004,6 +1004,19 @@ Préparation de publication minimale : `CHANGELOG.md`, `ROADMAP.md`, prompt de d
Publication stable mécanique après gates propres. Aucun Store Desk ni retry Store complet n'est requis pour fermer cette release.
État réconcilié avant le gate de `pre.009` :
```text
pre.001 -> pre.008-fix.001 livrés
pre.007-fix.003 gate entièrement vert
pre.008-fix.001 gate entièrement vert
PostgreSQL RawTransaction live PostgreSQL 17 PASS
pre.009 réconciliation documentaire en cours
pre.010 préparation de publication restant à faire
```
La fermeture `0.3.16` revendique uniquement les fondations multi-variantes, la promotion automatique strictement prouvée, le conflit durable minimal et la continuité Worker après quarantaine. Résolution opérateur complète, rétention/pins de variantes, retry Store, reconnect configurable et Store Desk restent explicitement dans `0.3.17`/`0.3.18`.
### 20.2 `0.3.17` — résilience opérationnelle et cycle de vie des variantes
Objectif de fermeture : rendre l'acquisition résiliente aux indisponibilités Store/Transport et fournir les contrats backend-neutral d'inspection/résolution nécessaires aux opérateurs et à la future UI.
@@ -1038,7 +1051,11 @@ Hardening cross-layer et preuves live ciblées : conflits concurrents, outage/re
#### `0.3.17-pre.008`
Gate technique final, réconciliation documentaire et préparation de `0.3.17-rel.001` ainsi que du prompt `0.3.18`.
Réconciliation documentaire finale : plan, validation, README/USAGE et références durables concernées.
#### `0.3.17-pre.009`
Préparation de publication minimale : `CHANGELOG.md`, `ROADMAP.md`, prompt `0.3.18`, version et delta obligatoires uniquement.
#### `0.3.17-rel.001`
@@ -1074,7 +1091,11 @@ Preuves end-to-end et gate technique/live final : PostgreSQL/Store/Worker/Desk,
#### `0.3.18-pre.007`
Réconciliation documentaire, `CHANGELOG.md`, `ROADMAP.md`, prompt de reprise suivant et préparation de `0.3.18-rel.001`.
Réconciliation documentaire finale : plan, validation, README/USAGE et références durables concernées.
#### `0.3.18-pre.008`
Préparation de publication minimale : `CHANGELOG.md`, `ROADMAP.md`, prompt de reprise suivant, version et delta obligatoires uniquement.
#### `0.3.18-rel.001`
@@ -1115,7 +1136,6 @@ Le Job Backfill actuel doit seulement rester compatible avec les contrats Store
Les décisions suivantes ne changent pas l'architecture du gate et peuvent être finalisées au moment où des mesures/tests réels existent :
- noms SQL définitifs des ressources V003 ;
- valeurs numériques par défaut de Store retry ;
- valeur par défaut du jitter et de `reset_after_stable_duration` Transport ;
- colonnes exactes des DataTables Store Desk ;

172
docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md
View File

@@ -1,11 +1,11 @@
<!-- file: docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Validation `0.3.16` -> `0.3.18` — résilience RAW et gestion des conflits
## 1. Objet
Ce document suit le programme de résilience RAW depuis le gate `0.3.16-pre.001` jusqu'à la fermeture prévue de `0.3.18`.
Ce document suit le programme de résilience RAW depuis le gate `0.3.16-pre.001` jusqu'à la fermeture prévue de `0.3.18`. La présente révision réconcilie spécifiquement l'état réellement validé de `0.3.16` avant sa lane de préparation de publication.
La première tranche ne prétend pas valider une implémentation qui n'existe pas encore. Elle valide le point de départ, les contrats acquis, les décisions d'architecture et la liste des preuves à construire. Le fix documentaire `0.3.16-pre.001-fix.001` répartit ensuite cette matrice sur trois releases stables afin de respecter la contrainte opérationnelle d'une version par session au maximum.
@@ -412,3 +412,171 @@ Le fix `0.3.16-pre.001-fix.001` ne supprime aucune preuve de la matrice ; il cha
Chaque stable possède son propre gate de fermeture. Une preuve non nécessaire au périmètre de la stable courante n'est pas déclarée manquante : elle reste explicitement attendue par la version suivante du programme.
Les scopes Backfill initialement réservés à `0.3.17` et `0.3.18` sont déplacés après ce programme afin d'éviter une collision de roadmap ; les cibles de planning par défaut deviennent respectivement `0.3.19` et `0.3.20`.
## 12. Réconciliation finale `0.3.16-pre.009`
### 12.1 Périmètre réellement acquis par `0.3.16`
La vertical slice `0.3.16` ferme les éléments suivants :
```text
Store API
RawTransactionVariantId / relation / reason code
comparateur partagé fail-closed
RawTransactionVariantWriteOutcome
RawAcquisitionWriteOutcome::transaction_variant()
PostgreSQL V003
ksp_raw_transaction_variants
ksp_raw_transaction_canonical_selectors
ksp_raw_transaction_observation_variants
ksp_raw_transaction_conflicts
Convergence
Exact -> observation/réutilisation de variante
CompatibleLessComplete -> variante observée, canonique inchangé
CompatibleMoreComplete -> promotion atomique
Conflict / Incomparable -> variante durable + conflict case Open, canonique inchangé
Worker
toute acquisition atteint le Store après sérialisation run-local par identité
QuarantinedConflict -> succès durable, Running + Degraded
identité suivante -> continue à être traitée
ERROR_CODE_RAW_CONFLICT legacy -> terminal de compatibilité
Job Backfill
QuarantinedConflict -> BackfillEntityPersistence::Conflict
outcome observation -> conservé, y compris AlreadyPresent
```
`content_hash` reste un préfiltre/intégrité et ne remplace jamais la comparaison des bytes lorsque ceux-ci sont disponibles. La seule dominance automatique admise en `0.3.16` reste la troncature `meta.logMessages` strictement prouvée ; les autres différences restent fail-closed.
### 12.2 Atomicité et rollback validés
Le hardening `pre.008` verrouille les invariants suivants :
- la branche de conflit ne modifie ni le sélecteur canonique ni la projection V001 ;
- les helpers de promotion et de conflict case restent dans la transaction d'acquisition externe ;
- un échec tardif après création de la variante divergente et du conflict case mais avant `COMMIT` annule ces écritures ;
- après rollback, selector et projection V001 restent cohérents avec le canonique antérieur ;
- deux écritures divergentes concurrentes produisent un canonique et une quarantaine durable, pas une erreur terminale de contenu.
### 12.3 Gate opérateur `0.3.16-pre.008-fix.001`
Le 22 septembre 2026, l'opérateur a exécuté :
```bash
cargo fmt --all
cargo fmt --all -- --check
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
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test -p ksp-store-api --all-targets --all-features
cargo test -p ksp-store-lib --all-targets --all-features
cargo test -p ksp-store-postgres-lib --all-targets --all-features
cargo test -p ksp-job-backfill-lib --all-targets --all-features
cargo test -p ksp-worker-raw-transaction-ingest-lib --all-targets --all-features
```
Résultats observés :
```text
cargo fmt --all -- --check PASS
General Rust rule audit clean
Rust export completeness audit 0 candidate(s)
KSP workspace Rust rule audit clean
Markdown table audit clean (352 table(s), 958 file(s))
cargo check --workspace PASS
cargo clippy --workspace --all-targets --all-features -D warnings PASS
ksp-store-api
29 unit + 2 dependency + 1 external backend + 9 public API
+ 5 release completeness + 5 security hardening PASS
ksp-store-lib
10 unit + 3 dependency + 1 feature mismatch
+ 6 hardening completeness + 5 public API PASS
ksp-store-postgres-lib
88 unit + 13 dependency + 16 hardening completeness
+ 13 public API + 3 V003 migration + 8 V003 variant PASS
foundation/raw-account/raw-transaction live tests ignored in normal gate as designed
ksp-job-backfill-lib
53 unit + 4 dependency + 9 hardening + 1 HTTP block material
+ 6 public API + 3 release + 2 WS parity + 1 Yellowstone PASS
ksp-worker-raw-transaction-ingest-lib
163 unit + 12 cross-layer + 21 dependency + 41 hardening
+ 22 public API + 18 release completeness PASS
```
Aucun warning Clippy n'est toléré par ce gate.
### 12.4 Preuve PostgreSQL réelle
Le live RawTransaction a été exécuté séparément avec une URI dédiée fournie silencieusement sur stdin :
```bash
read -rsp 'PostgreSQL URI: ' KSP_TEST_POSTGRES_URI
printf '\n'
printf '%s\n' "$KSP_TEST_POSTGRES_URI" \
| cargo test -p ksp-store-postgres-lib \
--test postgres_raw_transaction_live \
-- --ignored --nocapture
unset KSP_TEST_POSTGRES_URI
```
Résultat observé :
```text
KSP Store RawTransaction live proof: server major 17
test pre_009_real_postgres_raw_transaction_vertical_slice_is_atomic_concurrent_and_recoverable ... ok
1 passed; 0 failed
```
Cette preuve couvre notamment la concurrence divergente, la quarantaine durable, la cohérence selector/projection et le rollback tardif ajoutés au hardening `pre.008`.
### 12.5 Périmètre explicitement reporté
Ne sont **pas** revendiqués comme acquis par `0.3.16` :
```text
résolution/reopen/historique complet des conflict cases
rétention/pins/purge guards propres aux variantes
classification Store Transient/Terminal complète
retry Store / Blocked / backoff Worker
reconnexion WebSocket/Yellowstone configurable étendue
inspection/résolution de variantes via ksp-store-lib
Store Desk conflits/variantes/résolutions
Backfill multi-route/multi-stratégie
Backfill Desk multi-route
```
Les six premiers groupes appartiennent à `0.3.17`, Store Desk à `0.3.18`, puis les extensions Backfill sont ciblées par défaut sur `0.3.19`/`0.3.20`.
### 12.6 État de fermeture avant publication
```text
architecture/sizing CLOSED
Store API variantes/comparateur CLOSED
migration V003 CLOSED
variant ledger + observation mapping CLOSED
promotion canonique atomique CLOSED
conflit durable minimal CLOSED
Worker non terminal sur quarantaine CLOSED
régression Backfill CLOSED
hardening concurrence/rollback CLOSED
PostgreSQL RawTransaction live PASS sur PostgreSQL 17
gate technique pre.008-fix.001 PASS
réconciliation documentaire pre.009 CURRENT LANE
préparation publication pre.010 PENDING
rel.001 PENDING
```
La lane `pre.009` ne doit modifier ni `CHANGELOG.md`, ni `ROADMAP.md`, ni le prompt de démarrage `0.3.17`. Ces trois responsabilités appartiennent exclusivement à `pre.010`.