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

v0.3.13-pre.015

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-11 00:39:51 +02:00
parent 71bc754feb
commit 0cea99cd5e
5 changed files with 910 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
CHANGELOG.md
View File

@@ -1,8 +1,20 @@
<!-- file: CHANGELOG.md -->
<!-- version: 32 -->
<!-- version: 33 -->
# Changelog KSP
## 0.3.13 — convergence live multi-source du Worker RawTransaction — 2026-09-10
`0.3.13` généralise `ksp-worker-raw-transaction-ingest-lib` de la verticale Yellowstone de `0.3.12` vers une composition caller-owned de `1..32` sources logiques appartenant au même réseau. Cinq familles live convergent désormais vers le même pipeline Common RAW / admission / Store : Yellowstone, Standard Logs avec hydration `getTransaction observed`, Standard Block RAW-direct, Helius `transactionSubscribe` avec hydration et HTTP Block Polling run-local RAW-direct. Le Worker reste sans Config, Job Backfill, backend Store physique, client réseau direct ou SDK provider parallèle.
La convergence partage un registre global d'hydration entre Yellowstone, Standard Logs et Helius afin de coalescer `(network, signature, commitment)` avant fan-out HTTP. Après canonicalisation, les acquisitions de même `(network, signature)` sont sérialisées de manière bornée : un contenu identique conserve les observations/provenances distinctes, tandis qu'une divergence devient un `content_conflict` terminal explicite. Aucune majorité provider, préférence silencieuse ou stratégie `first-provider-wins` n'est introduite. Standard Block et HTTP Block Polling admettent directement les transactions Legacy/V0/V1 qualifiées avec `maxSupportedTransactionVersion = 1`.
Le supervisor multi-source possède toutes les tâches et applique des bornes source-neutral sur admission, pending signals, hydrations et persistence avec une fairness minimale entre sources reference-bearing. Les snapshots agrègent activity/health/backpressure/reconnect/replay/gap sans exposer le matériau provider. La politique reste conservative : une source configurée qui échoue est terminale faute d'équivalence de coverage prouvée ; le gap repair, les rôles degraded/failover et la preuve de couverture restent donc `0.3.14`. Le shutdown stop/fault/drain/abort+join est durci contre les races, leaders d'hydration abandonnés, Store lent et publications tardives.
Le gate déterministe final passe `cargo fmt`, audits Rust/Markdown, `cargo check --workspace`, Clippy workspace/all-targets/all-features avec `-D warnings`, `cargo test --workspace --all-targets --all-features` et les graphes Cargo : `1 850` tests passent, `0` échoue et `15` restent ignored opt-in/operator-only. Les smokes keyless Solana HTTP Devnet et WebSocket Devnet passent `1/1` chacun. Yellowstone provider-gated, Helius `transactionSubscribe` live, `blockSubscribe` provider dédié, HTTP polling Worker end-to-end et Worker multi-source vers Store restent explicitement non exécutés faute de gate provisionné ; aucune fixture ne les requalifie en PASS.
`prompts/033-V0_3_14_START_PROMPT.md` ouvre `0.3.14` exclusivement depuis le futur tag stable `v0.3.13`. Cette release doit fermer le gap repair/hardening multi-source limité au run actif — replay adressable, coverage redondante, scan HTTP borné, hydration de réparation, unresolved gaps et health policy — sans transformer le Worker en moteur historique ni créer de dépendance vers `ksp-job-backfill-lib`.
## 0.3.12 — Yellowstone + hydration HTTP + continuité de run du Worker RawTransaction — 2026-09-09
`0.3.12` ouvre la première source réseau productive de `ksp-worker-raw-transaction-ingest-lib` sans remettre en cause la fondation source-neutral de `0.3.11`. Le Worker dépend désormais de la façade `ksp-onchain-transport-lib` mais reste sans Config, Job Backfill, backend Store physique, `reqwest`, `tonic` ou proto provider direct. `RawTransactionIngestRuntimeResources` reçoit une source Yellowstone caller-composed et un pool HTTP cohérent ; `start` conserve la fondation sans source, tandis que `start_with_runtime_resources` lance la verticale live supervisée.

4
Cargo.toml
View File

@@ -1,12 +1,12 @@
# file: Cargo.toml
# version: 563
# version: 564
[workspace]
resolver = "3"
members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-raw-transaction-lib", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api", "crates/ksp-worker-raw-transaction-ingest-lib"]
[workspace.package]
version = "0.3.13-pre.14"
version = "0.3.13-pre.15"
edition = "2024"
license = "MIT"
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

6
ROADMAP.md
View File

@@ -1,5 +1,5 @@
<!-- file: ROADMAP.md -->
<!-- version: 110 -->
<!-- version: 111 -->
# Roadmap KSP
@@ -105,7 +105,7 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
- [X] `0.3.10` — Lower-layer RAW Transaction commune stabilisée : `ksp-raw-transaction-lib` possède la canonicalisation RAW v1 source-neutral partagée, le Backfill est migré sans changement des golden bytes/hash, Transport expose `get_block_observed`, le wire Solana Legacy/V0/V1 est matérialisé et les canaris HTTP/WS standard/Helius/Yellowstone qualifient précisément les voies directes ou nécessitant hydration. La release se ferme sans runtime Worker concret ; celui-ci commence en `0.3.11` selon le redécoupage `0.3.11`–`0.3.14`.
- [X] `0.3.11` — Fondation runtime de `ksp-worker-raw-transaction-ingest-lib` livrée : crate/dependency firewall, settings source-neutral, handle/start-stop, lifecycle, snapshots, supervisor, admission bornée, canonicalisation Common RAW, persistence/déduplication Store déterministe, backpressure et shutdown/fault hardening. La release se ferme volontairement sans source réseau productive ; Yellowstone + hydration HTTP commencent en `0.3.12`.
- [X] `0.3.12` — Première source live productive du Worker livrée : Yellowstone `Transaction`/`TransactionStatus`/`Block` vers signaux source-neutral, coalescence bornée puis hydration HTTP `getTransaction` observed avant Common RAW/Store ; `BlockMeta`/`Slot` restent continuity-only. Processing frontier run-local, reconnect/from_slot/ReplayInfo Transport-owned, compteurs source-neutral et fault sur gap de rétention prouvé sans Backfill automatique. Hardening duplicate/backpressure/stop/fault et canaris cross-layer fermés ; gate workspace complet vert, smokes live HTTP Devnet + WebSocket Devnet verts, Yellowstone token-gated/Worker end-to-end laissés explicitement non exécutés.
- [ ] `0.3.13` — Ajouter les voies **WS standard / Helius / HTTP live** et leur convergence multi-source : `logsSubscribe + getTransaction`, `blockSubscribe`, `transactionSubscribe + hydration`, polling blocs HTTP, observations multiples, content conflict explicite, coalescence et backpressure sans second actor Transport.
- [X] `0.3.13` — Convergence live multi-source du Worker RAW livrée : composition caller-owned `1..32` sources d’un même réseau, cinq familles Yellowstone / Standard Logs / Standard Block / Helius Transaction / HTTP Block Polling, hydration globale des trois voies reference-bearing, RAW-direct Legacy/V0/V1 pour les deux voies blocs, observations multiples, content conflict explicite, coalescence cross-source, fairness/backpressure/health source-neutral et shutdown hardening sans second actor Transport. Gate workspace complet vert (`1 850` PASS / `0` échec / `15` ignored) et smokes keyless HTTP + WebSocket Devnet verts ; les preuves provider/resource-gated non exécutées restent explicitement non revendiquées.
- [ ] `0.3.14` — Fermer le Worker par le **gap repair/hardening multi-source** : replay natif, source redondante, scan HTTP blocs, hydration de réparation, unresolved gaps visibles, politiques degraded/unhealthy/faulted, shutdown pendant repair, smokes provider accessibles et adapter EARLY seulement si réellement prouvé.
- [ ] `0.3.15` — Introduire `ksp-app-raw-transaction-ingest-desk`, Desk Tauri KSP spécialisée qui choisit et supervise une ou plusieurs sources/méthodes réellement admises par le Worker finalisé : lifecycle, health, rates, backpressure, reconnect/recovery, gap state et compteurs sûrs. La Desk ne réimplémente ni discovery, hydration, déduplication, reprise ni persistence.
- [ ] `0.3.16` — Étendre `ksp-job-backfill-lib` et `ksp-app-backfill-desk` au **backfill multi-source/multi-stratégie** à partir de la même matrice d'acquisition auditée en `0.3.9`. Conserver la stratégie actuelle `getSignaturesForAddress + getTransaction` comme première voie HTTP valide, puis ajouter seulement les voies historiques/catch-up/gap-repair réellement pertinentes et sûres, sans supposer qu'une source live WS constitue un historique universel.
@@ -119,7 +119,7 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
- [ ] **TODO** — maintenir la matrice d’admission HTTP/WS/gRPC/provider lors de toute nouvelle famille D1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte.
- [X] **TODO `0.3.9`** — matrice RAW Transaction unique produite et consolidée dans `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`, avec séparation possibilités/support/preuve, capabilities orthogonales aux producteurs, provenance/déduplication/continuité et handoffs désormais scindés `0.3.11`–`0.3.14` Worker live / `0.3.16` Backfill historique.
- [ ] **TODO Helius `0.3.13`** — ajouter uniquement les profils/capabilities Helius réellement nécessaires au Worker live après revalidation des surfaces/tier courants ; réutiliser exclusivement `KSP_SECRET_HELIUS_API_KEY` via Config et la surface `transactionSubscribe` déjà Transport-owned, sans SDK provider ni second client parallèle.
- [X] **TODO Helius `0.3.13`** — la voie Worker Helius `transactionSubscribe` réutilise la surface Transport et les profils Config Helius déjà existants avec `KSP_SECRET_HELIUS_API_KEY`; aucun nouveau profil, secret, SDK provider, tier codé ou second client parallèle n’a été nécessaire. Le payload riche reste Transport-owned et la voie Worker hydrate via `getTransaction observed` tant que le RAW complet n’est pas prouvé directement.
- [X] **TODO réseau** — identité KSP canonique fixée à `mainnet` dans Config/Store/Transport/tests ; `mainnet-beta` reste uniquement un alias legacy/externe lorsque la frontière provider l'exige. Les données D1 RAW antérieures restent non autoritaires pendant cette phase et aucune compatibilité de base de test n'impose l'ancien libellé.
- [X] `RawAccountState` + observation — contrat commun stabilisé en `0.3.1` avec bytes complets + slot, provenance séparée et enrichissements source-specific optionnels ; la persistence PostgreSQL physique est complétée en `0.3.4` avec les quatre capabilities account et la conformance RAW 10/10.
- [ ] **TODO** — statut/commitment transactionnel restant : `0.3.5` couvre uniquement le fait passif d’exécution `slot + signature + outcome`; réauditer séparément `signatureSubscribe` et `getSignatureStatuses` lorsqu’un consumer de commitment/snapshot réel apparaît, sans fusionner snapshot, transition et execution update dans un modèle Option-soup.

224
deltas/0.3.13/pre.015.md Normal file
View File

@@ -0,0 +1,224 @@
<!-- file: deltas/0.3.13/pre.015.md -->
<!-- version: 2 -->
# Delta `0.3.13-pre.015` — préparation de publication
## 1. Base requise
```text
0.3.13-pre.014
workspace.package.version = 0.3.13-pre.14
```
Le gate opérateur communiqué le **10 septembre 2026 à 23:15** sur `pre.014` est vert pour toutes les commandes exécutées :
```text
cargo fmt --all : PASS
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, 340 tables / 852 files
cargo check --workspace : PASS
cargo clippy --workspace --all-targets --all-features -- -D warnings : PASS
```
Conformément à `pre.014`, aucun `cargo tree`, smoke live ou rerun exhaustif des tests n'était requis pour cette tranche strictement documentaire hors bump mécanique.
## 2. Objectif
`pre.015` est la dernière prerelease de préparation de publication de `0.3.13`.
Conformément à `VER-LIFECYCLE-003`, `VER-LIFECYCLE-012` et `PROMPT_STRUCTURE.md`, elle modifie fonctionnellement uniquement :
```text
prompt de démarrage 0.3.14
CHANGELOG.md
ROADMAP.md
```
Les seuls fichiers mécaniques supplémentaires sont :
```text
Cargo.toml racine
delta pre.015
```
Aucun README, USAGE, plan, validation, architecture, code, test, Config, schema, dépendance, feature ou manifest de crate n'est rouvert.
## 3. Version workspace
La prerelease non-fix synchronise Cargo :
```text
0.3.13-pre.14
->
0.3.13-pre.15
```
Le header de `Cargo.toml` passe de `563` à `564`.
## 4. Prompt suivant
Le nouveau prompt :
```text
prompts/033-V0_3_14_START_PROMPT.md
```
ouvre `0.3.14` exclusivement depuis le futur stable :
```text
v0.3.13
```
Sa mission est bornée au gap repair/hardening multi-source du run actif :
```text
replay natif réellement adressable
preuve de coverage par source redondante
scan HTTP de slots/blocs du run
hydration getTransaction de réparation
repaired vs unresolved gap explicites
health Healthy/Degraded/Unhealthy/Faulted fondée sur coverage prouvée
backpressure/fairness et shutdown pendant repair
smokes provider réellement accessibles
EARLY uniquement si pre.001 apporte une preuve actuelle suffisante
```
Le prompt interdit explicitement de transformer le Worker en campagne historique, de créer un edge Worker -> Job Backfill ou de coder le repair avant le `pre.001` d'audit/sizing. Il réserve :
```text
docs/plans/035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md
docs/validation/031-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING.md
```
## 5. CHANGELOG
`CHANGELOG.md` reçoit l'entrée stable `0.3.13` synthétisant :
```text
composition 1..32 sources d'un même réseau
cinq familles live productives
hydration globale Yellowstone / Standard Logs / Helius
RAW-direct Standard Block / HTTP Block Polling Legacy/V0/V1
coalescence cross-source + observations multiples
content conflict explicite sans first-provider-wins
fairness/backpressure/health source-neutral
shutdown/races hardening
gate déterministe 1 850 PASS / 0 échec / 15 ignored
smokes keyless HTTP Devnet + WebSocket Devnet PASS
preuves provider/resource-gated restantes NON EXÉCUTÉES
handoff 0.3.14 et prompt 033
```
## 6. ROADMAP
L'entrée `0.3.13` passe de `[ ]` à `[X]` et décrit l'état réellement livré. `0.3.14` reste ouverte pour le gap repair/hardening multi-source.
Le TODO Helius `0.3.13` passe également à `[X]` en documentant le résultat réel : la voie Helius Worker réutilise les profils Config et `KSP_SECRET_HELIUS_API_KEY` déjà existants ainsi que `transactionSubscribe` Transport-owned ; aucun nouveau profil, SDK, tier codé ou second client n'a été nécessaire.
## 7. Fichiers ajoutés
```text
prompts/033-V0_3_14_START_PROMPT.md
deltas/0.3.13/pre.015.md
```
## 8. Fichiers modifiés
```text
Cargo.toml
CHANGELOG.md
ROADMAP.md
```
## 9. Fichiers supprimés
```text
aucun
```
## 10. Surfaces explicitement inchangées
```text
README.md
RULES.md
docs/**
crates/**
config/**
tests/**
prompts/001-* à prompts/032-*
deltas/0.3.13/pre.001.md à pre.014.md et leurs fixes
```
Aucun delta historique n'est modifié.
## 11. Vérification complète de l'archive de base avant modification
L'archive opérateur `v0.3.13-pre.014` a été contrôlée avant assemblage :
```text
unzip -t : PASS
2 009 entrées ZIP
0 chemin absolu / traversal / entrée hors racine attendue
0 target/node_modules/dist/.git/.idea/__pycache__ embarqué
0 lockfile embarqué
rust-toolchain.toml absent
General Rust rule audit : clean
Rust export completeness audit : 0 candidate(s)
KSP workspace Rust rule audit : clean
Markdown table audit : clean, 340 tables / 852 files
5/5 tests unitaires du validateur Markdown : PASS
489 définitions de règles normatives
489 identifiants normatifs uniques
0 doublon d'identifiant normatif
headers/newline des surfaces critiques : PASS
scan high-confidence de secrets privés : aucun résultat
```
Le toolchain Cargo/Rustc n'est pas disponible dans l'environnement d'assemblage. Aucun PASS Cargo supplémentaire n'est revendiqué localement ; les PASS Cargo ci-dessus proviennent exclusivement du gate opérateur communiqué.
## 12. Validations exécutées sur l'état `pre.015`
Sur l'état exact de `pre.015` avant packaging :
```text
General Rust rule audit : clean
Rust export completeness audit : 0 candidate(s)
KSP workspace Rust rule audit : clean
Markdown table audit : clean, 340 tables / 854 files
489 définitions de règles / 489 identifiants uniques / 0 doublon
prompt 033 : 16 sections normatives présentes
diff exact pre.014 -> pre.015 : 3 fichiers existants modifiés + 2 ajoutés + 0 supprimé
headers des 3 fichiers existants : +1 exactement
Cargo.toml : hors header, seule workspace.package.version change
aucun README/USAGE/plan/validation/architecture/code/test/config/schema/dependency/feature modifié
```
Les contrôles `unzip -t`, archive safety et inventaire minimal du ZIP sont exécutés après packaging avant livraison.
Les commandes Cargo post-`pre.015` restent à exécuter par l'opérateur avant `rel.001` :
```bash
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
```
Clippy strict peut être rejoué ; aucun code/test/dépendance/feature n'étant modifié, il ne remplace pas le gate minimal ci-dessus.
## 13. Décisions prises
- `0.3.13` est fonctionnellement/documentairement fermé et prêt pour le gate de publication de `pre.015` ;
- `0.3.14` ne commence qu'après `0.3.13-rel.001` validée et le tag stable `v0.3.13` ;
- le prompt `0.3.14` conserve la séparation Worker/Backfill et impose un `pre.001` avant toute logique de repair ;
- les preuves live non exécutées de `0.3.13` restent explicitement non revendiquées ;
- aucun correctif d'un couloir technique/documentaire antérieur n'est absorbé dans cette préparation de publication.
## 14. Questions ouvertes
```text
aucune question bloquante pour la préparation de publication 0.3.13
```

668
prompts/033-V0_3_14_START_PROMPT.md Normal file
View File

@@ -0,0 +1,668 @@
<!-- file: prompts/033-V0_3_14_START_PROMPT.md -->
<!-- version: 2 -->
# Prompt de démarrage `0.3.14` — gap repair / hardening multi-source du Worker `RawTransaction`
## 1. Identité de la release et base exacte requise
Ouvrir **uniquement** `0.3.14` depuis la release stable/taggée :
```text
v0.3.13
```
La base de travail fournie par l'opérateur est autoritaire sur les souvenirs, snippets, anciennes archives et deltas intermédiaires. Avant toute modification, vérifier au minimum :
```text
workspace.package.version = 0.3.13
deltas/0.3.13/rel.001.md présent
ksp-worker-raw-transaction-ingest-lib présent avec composition 1..32 sources d'un même réseau
cinq familles live productives présentes : Yellowstone / Standard Logs / Standard Block / Helius Transaction / HTTP Block Polling
Yellowstone / Standard Logs / Helius partagent l'hydration globale getTransaction observed
Standard Block / HTTP Block Polling restent RAW-direct sur Legacy/V0/V1 qualifiés
convergence canonique network/signature + observations multiples + content conflict explicite
source failure encore terminale faute d'équivalence de coverage prouvée
processing frontier encore run-local, sans checkpoint durable ni campagne historique
Worker sans dépendance Config/Job/backend Store direct
ksp-store-lib reste la seule façade Store du Worker
```
Release ouverte :
```text
0.3.14
```
Première livraison attendue :
```text
0.3.14-pre.001
```
`pre.001` est obligatoirement un gate de **lecture + audit interne/externe + brainstorming + sizing + planification**. Il ne commence pas directement un moteur de repair, une politique degraded/failover ou un adapter EARLY. Si le périmètre réel n'est pas clôturable dans une seule session ou si une tranche paraît dépasser environ 15–20 minutes de travail effectif, rescinder avant l'implémentation lourde.
## 2. Mission et résultat attendu
### 2.1 Mission de `0.3.14`
Fermer le Worker continu `RawTransaction` par la **réparation de continuité limitée au run actif** et le hardening multi-source qui restaient volontairement hors `0.3.13` :
```text
replay natif lorsqu'il est réellement adressable par Transport/provider
preuve de couverture par source live redondante
scan HTTP de slots/blocs pour réparer une plage manquante du run
hydration getTransaction des références manquantes lorsque nécessaire
réconciliation explicite des gaps avant reprise normale
unresolved gaps observables et bornés
politiques Healthy / Degraded / Unhealthy / Faulted fondées sur des preuves de coverage
backpressure/fairness pendant repair
shutdown/fault pendant replay/scan/hydration/persistence
smokes provider réellement accessibles
adapter EARLY uniquement si pre.001 apporte une preuve actuelle suffisante et un périmètre borné
```
Le Worker ne devient pas un moteur historique paramétré. Une demande arbitraire telle que « récupère le programme X depuis le slot Y » reste la responsabilité indépendante de `ksp-job-backfill-lib` et de la trajectoire `0.3.16`.
### 2.2 Pipeline durable à préserver
Le chemin nominal `0.3.13` reste le cœur unique :
```text
source live
-> signal ou matériau source/protocole
-> hydration si nécessaire
-> ksp-raw-transaction-lib
-> RawTransaction + RawTransactionObservation
-> admission centrale Worker
-> ksp-store-lib
```
Le repair ajoute un chemin de continuité autour de ce cœur, pas un second pipeline :
```text
preuve de gap du run
-> qualification de la plage et des capabilities disponibles
-> replay Transport OU coverage redondante OU scan HTTP borné
-> hydration éventuelle
-> même Common RAW / même admission / même Store
-> preuve de réconciliation OU unresolved gap explicite
-> reprise live
```
Ordre architectural déjà acquis pour un gap du run, sous réserve des capabilities réellement prouvées :
```text
1. replay adressable du stream depuis le frontier connu
2. source live redondante ayant réellement couvert la plage
3. HTTP getBlock/getTransaction pour les slots/références manquants
4. reprise live après réconciliation
```
Aucune étape ne reçoit de requête historique arbitraire du caller.
## 3. Sources de vérité internes obligatoires — ordre de lecture
### 3.1 Gouvernance générale
Lire intégralement, dans cet ordre :
```text
RULES.md
ROADMAP.md
CHANGELOG.md
docs/000-README.md
docs/rules/RULES_GENERAL.md
docs/rules/RULES_KSP.md
docs/rules/RULES_RUST.md
docs/rules/RULES_DEPENDENCIES.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/FILE_CONTRACTS.md
docs/rules/VERSION_WORKFLOW.md
docs/rules/PROMPT_STRUCTURE.md
```
Le prompt complète ces règles ; il ne les remplace pas.
Rappels Rust bloquants :
```text
Rust 2024
unsafe interdit
unwrap / expect / panic interdits selon les règles KSP
? interdit en production
retours explicites ; clippy::implicit_return deny
#![warn(missing_docs)]
#![deny(unreachable_pub)]
#![forbid(unsafe_code)]
pas de pub mod
pub/pub(crate) partagés reexportés jusqu'à la crate root
accès partagés via crate::Item, y compris intra-crate
item strictement module-local => private
unit tests sous unit_tests/
integration tests sous tests/
```
Après toute modification Rust :
```bash
cargo fmt --all
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets
```
Pour tout Markdown touché :
```bash
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
```
Une commande non exécutée n'est jamais déclarée PASS.
### 3.2 Handoff stable `0.3.13`
Lire intégralement :
```text
docs/plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md
docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md
deltas/0.3.13/pre.013.md
deltas/0.3.13/pre.014.md
deltas/0.3.13/pre.015.md
deltas/0.3.13/rel.001.md
crates/ksp-worker-raw-transaction-ingest-lib/README.md
crates/ksp-worker-raw-transaction-ingest-lib/USAGE.md
crates/ksp-worker-raw-transaction-ingest-lib/src/
crates/ksp-worker-raw-transaction-ingest-lib/tests/
crates/ksp-worker-raw-transaction-ingest-lib/unit_tests/
```
La convergence multi-source `0.3.13` est une base à préserver, pas un prototype à remplacer.
### 3.3 Architecture RAW, continuité et séparation Worker/Job
Lire intégralement :
```text
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/005-DEPENDENCY_GRAPH.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
crates/ksp-job-backfill-lib/README.md
crates/ksp-job-backfill-lib/USAGE.md
crates/ksp-raw-transaction-lib/README.md
crates/ksp-raw-transaction-lib/USAGE.md
crates/ksp-store-api/src/
crates/ksp-store-lib/src/
```
Porter une attention particulière à :
```text
continuité Worker limitée au run courant
reconnect réussi != absence de gap
replay attempt != preuve de repair réussi
processing frontier != blockchain completeness
Store durable != coverage du réseau
Worker -X-> Job Backfill
Job Backfill -X-> Worker
aucun checkpoint partagé Worker/Job
même identité + même contenu -> idempotence + observations distinctes
même identité + contenu divergent -> content conflict explicite
```
### 3.4 Transport et capabilities de replay/repair
Lire au minimum :
```text
crates/ksp-onchain-transport-lib/Cargo.toml
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/yellowstone_*.rs
crates/ksp-onchain-transport-lib/src/ws_*.rs
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
crates/ksp-onchain-transport-lib/src/rpc_blocks.rs
crates/ksp-onchain-transport-lib/src/http_*.rs
crates/ksp-onchain-transport-lib/tests/
```
Réutiliser les sessions/actors Transport existants. Il est interdit de recréer dans le Worker :
```text
socket WebSocket bas niveau parallèle
client Yellowstone/Helius parallèle
client reqwest direct
reconnect/resubscribe actor concurrent
seconde boucle de retry autour des primitives Transport
SDK provider pour contourner Transport
```
Le Worker ne doit pas écrire arbitrairement `from_slot` ni interpréter un message provider brut lorsque Transport possède déjà la sémantique correspondante.
### 3.5 Config, providers et secrets
Lire :
```text
crates/ksp-config-lib/src/transport.rs
config/std.transport.json
config/examples/std.transport.example.json
config/schemas/std.transport.schema.json
.env.example
```
Config reste l'unique propriétaire des endpoints, profils, capabilities et secrets. Le Worker ne lit jamais l'environnement et ne reçoit jamais une clé API comme payload métier.
Une modification Config n'est autorisée que si `pre.001` prouve un besoin réel non satisfait par les profils existants. Aucun tier, quota ou prix provider n'est codé dans le Worker.
## 4. Sources externes normatives et fraîcheur à réauditer
Au début de `pre.001`, réauditer les surfaces courantes depuis les sources primaires réellement actuelles :
```text
Solana RPC / WebSocket
getSlot
getBlocks / getBlocksWithLimit
getBlock
getTransaction
logsSubscribe / blockSubscribe et sémantique de reconnexion pertinente
Yellowstone gRPC upstream
Subscribe
from_slot
SubscribeReplayInfo / first_available lorsque présents dans la version réellement utilisée
limites et sémantique de replay réellement exposées
Providers réellement candidats/configurés
profondeur de replay actuelle
réseaux disponibles
auth/tier/quota actuels
comportement de first_available / rétention
éventuelles APIs historiques distinctes du live
Helius et autres surfaces EARLY seulement si elles sont réellement reconsidérées
matériau disponible
finalité/exécution prouvable
nécessité d'hydration
disponibilité/tier actuel
```
Les prix, profondeurs de replay, quotas et entitlements historiques de `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md` sont des traces datées, pas des constantes à recopier sans revalidation.
Si les crates/projets primaires concernés ont évolué, vérifier leurs versions stables courantes, features nécessaires et contraintes transitives avant toute modification.
## 5. État validé à préserver
La base stable `0.3.13` apporte déjà :
```text
RawTransactionIngestRuntimeResources : 1..32 sources logiques, même réseau, identités uniques
Yellowstone productive
Standard Logs -> getTransaction observed -> Common RAW
Standard Block -> RAW-direct Legacy/V0/V1 qualifié
Helius Transaction -> getTransaction observed -> Common RAW
HTTP Block Polling -> RAW-direct Legacy/V0/V1, borne initiale du run
registre global d'hydration Yellowstone / Standard Logs / Helius
coalescence network/signature/commitment avant hydration
sérialisation run-local des acquisitions network/signature
observations multiples conservées
content conflict explicite sans majorité ni first-provider-wins
quotas/backpressure/fairness bornés
health source-neutral conservative
shutdown/fault/drain/abort/join bornés
```
Le gate technique `0.3.13` a qualifié le workspace déterministe et les smokes keyless HTTP/WebSocket Devnet. Les smokes provider/token/resource-gated non exécutés restent non exécutés ; `0.3.14` ne doit pas les réécrire comme PASS sans nouveau résultat réel.
État de continuité à l'ouverture :
```text
reconnect/replay natif reste Transport-owned
processing_frontier_slot reste run-local
continuity gap prouvé reste terminal dans 0.3.13
aucune preuve de coverage équivalent entre sources n'autorise encore un failover non terminal
aucun moteur HTTP de repair rétroactif du run n'est encore fermé
aucun unresolved-gap model public final n'est encore stabilisé
aucun adapter EARLY n'est retenu par défaut
```
## 6. Décisions acquises et questions réellement ouvertes
### 6.1 Décisions acquises
```text
repair Worker = continuité de son run actif uniquement
Backfill = historique paramétré/borné indépendant
aucune dépendance Worker <-> Job Backfill
Transport possède reconnect/resubscribe/retry et replay natif qu'il sait adresser
Worker possède la réconciliation source-neutral de ses gaps observés
Common RAW et Store restent le chemin unique de matérialisation/persistence
content conflict reste terminal et explicite
une source redondante ne prouve un repair que si sa coverage de la plage est démontrée
un skipped/non-produced slot ne doit pas être inventé comme transaction manquante
un gap non réparé doit rester visible et ne peut pas être effacé par une reprise live
aucun exactly-once blockchain n'est revendiqué
```
### 6.2 Questions ouvertes à fermer en `pre.001`
```text
forme minimale du gap/range run-local et de son identité
preuve de coverage par famille de source sans exposer le matériau provider
preuve qu'un replay Transport a réellement couvert la plage demandée
traitement exact des skipped slots et slots temporairement indisponibles
bornes de scan HTTP et politique de retry sans doubler Transport
critère atomique « repaired » vs « unresolved »
interaction entre repair et processing frontier existante
politique required/redundant et transitions Healthy/Degraded/Unhealthy/Faulted
priorité entre plusieurs mécanismes de repair simultanément disponibles
quotas/fairness entre trafic nominal et trafic de repair
projection snapshot des gaps sans fuite d'identité provider sensible
smokes réellement possibles avec les ressources opérateur
EARLY : rejet confirmé ou adapter dédié réellement justifié/provable
```
Une question ouverte n'est pas résolue arbitrairement avant l'audit.
## 7. Objectifs, livrables et hors périmètre
### 7.1 Livrables de release
`0.3.14` doit aboutir, selon le sizing validé, à :
```text
modèle source-neutral de gap/coverage run-local
repair par replay natif lorsque Transport le prouve adressable
repair par source redondante lorsque sa coverage est démontrée
repair HTTP borné par slots/blocs/références du run
hydration de réparation via les façades Transport existantes
réconciliation explicite repaired/unresolved avant reprise
health policy multi-source fondée sur coverage réelle
backpressure/fairness bornés avec trafic de repair
observabilité source-neutral des gaps et repairs
shutdown/fault déterministe pendant toute phase de repair
canaris cross-layer/security/completeness
smokes réellement accessibles ou statut NON EXÉCUTÉ explicite
plan/validation/documentation réconciliés
prompt 0.3.15 dans la dernière prerelease
```
### 7.2 Hors périmètre
```text
campagne historique arbitraire pilotée par le Worker
appel ou orchestration automatique de ksp-job-backfill-lib
checkpoint durable partagé Worker/Job
Backfill multi-source/multi-stratégie 0.3.16
ksp-app-raw-transaction-ingest-desk 0.3.15
persistence STRUCTURAL/DECODED/DOMAIN
exactly-once réseau/provider
majorité provider ou overwrite d'un content conflict
second actor/client Transport dans Worker
provider SDK contournant ksp-onchain-transport-lib
nouveau système de secrets hors Config
EARLY sans preuve actuelle suffisante
```
## 8. Contraintes sécurité / API / architecture spécifiques
Les frontières suivantes sont bloquantes :
```text
Worker -> ksp-onchain-transport-lib : autorisé
Worker -> ksp-raw-transaction-lib : autorisé
Worker -> ksp-store-lib : autorisé
Worker -> ksp-config-lib : interdit
Worker -> ksp-job-backfill-lib : interdit
Worker -> backend Store physique : interdit
Worker -> reqwest/tokio-tungstenite/tonic/proto provider direct : interdit
```
Le caller compose les ressources déjà résolues. Le Worker ne reçoit ni endpoint brut non validé, ni token, ni API key comme paramètre métier.
Le repair doit être borné en mémoire, nombre de ranges, taille de plage, nombre de requêtes simultanées, hydrations in-flight et files d'attente. Toute nouvelle borne publique possède validation, tests de limites et diagnostics redacted.
Une source perdue ne devient pas silencieusement optionnelle. Toute transition non terminale après perte d'une source doit être justifiée par une preuve explicite que les autres mécanismes couvrent réellement le même intervalle pertinent.
Un mécanisme de repair ne contourne jamais l'idempotence/conflit Store : tout matériau réparé repasse par Common RAW et l'admission centrale.
## 9. Première mission `pre.001` — audit / brainstorming / sizing
`pre.001` doit exécuter et documenter, avant codage lourd :
1. vérification exacte de la base stable `v0.3.13` et de `deltas/0.3.13/rel.001.md` ;
2. lecture complète des sources internes listées ci-dessus ;
3. inventaire du modèle actuel de frontier/reconnect/replay/continuity counters dans Worker et Transport ;
4. audit externe courant Solana/Yellowstone/providers réellement concernés ;
5. matrice par famille live : capacité à détecter un gap, rejouer, prouver coverage, hydrater, scanner, reprendre ;
6. distinction formelle reconnect / replay attempt / replay covered / repair / unresolved gap ;
7. modèle cible minimal de gap/range/coverage run-local, privé ou public selon consumer réel ;
8. algorithme borné de sélection du mécanisme de repair sans campagne historique ;
9. sémantique skipped slots / missing block / Missing transaction / provider retention ;
10. politique de concurrence entre trafic nominal et repair, avec backpressure/fairness ;
11. politique de health required/redundant et critères de retour à Healthy ;
12. threat model : reconnect storms, overlapping gaps, stale redundant source, replay truncation, HTTP holes, duplicate repair, content disagreement, slow Store, stop/fault pendant repair ;
13. inventaire des smokes provider réellement accessibles avec les ressources opérateur ;
14. décision explicite sur EARLY : hors scope confirmé ou tranche dédiée justifiée par preuve ;
15. graphes Cargo/features cibles et éventuels changements Transport/Config strictement nécessaires ;
16. sizing de chaque tranche sous le budget 15–20 minutes ;
17. décision explicite : maintien de `0.3.14` ou rescission avant codage ;
18. création du plan et de la validation de release.
Documents attendus :
```text
docs/plans/035-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING_PLAN.md
docs/validation/031-V0_3_14_MULTI_SOURCE_GAP_REPAIR_HARDENING.md
```
Critère de sortie : aucun mécanisme de repair n'est implémenté tant que sa source de preuve du gap, sa plage, ses bornes, son propriétaire de retry/reconnect, son critère de succès et son échec unresolved ne sont pas définis.
## 10. Prévision souple initiale des prereleases
Cette prévision est un point de départ à recalibrer par `pre.001`.
### `pre.001` — audit / brainstorming / sizing
Base stable, audit replay/coverage/provider courant, modèle gap/range, stratégie repair, health, threat model, smokes, graphes, plan/validation et décision de maintien/rescission.
### `pre.002` — contrats gap / range / coverage
Stabiliser les identités et invariants run-local nécessaires à la réparation, avec bornes et distinction repaired/unresolved, sans encore lancer tous les mécanismes.
### `pre.003` — replay natif + coverage redondante
Intégrer la preuve source-neutral d'un replay Transport réellement exploitable et la preuve de couverture par une source redondante, sans faire écrire `from_slot` au Worker ni supposer l'équivalence des sources.
### `pre.004` — scan HTTP de réparation
Réparer une plage du run via les primitives HTTP Transport existantes, avec découverte de slots/blocs bornée, skipped slots explicites et aucune plage historique arbitraire.
### `pre.005` — hydration de réparation
Fermer les références/signatures manquantes via `getTransaction observed`, partager les bornes/coalescences pertinentes et conserver Common RAW comme unique canonicalizer.
### `pre.006` — réconciliation et reprise live
Unifier replay/redondance/HTTP/hydration dans une machine de réparation run-local qui ne reprend le nominal qu'après preuve repaired ou publie unresolved/fault selon la politique décidée.
### `pre.007` — health policy multi-source
Fermer les rôles required/redundant réellement justifiés, les transitions Healthy/Degraded/Unhealthy/Faulted et les conditions de récupération sans masquer une perte de coverage.
### `pre.008` — backpressure et fairness pendant repair
Borner ranges, scans, hydrations et persistence sous concurrence avec le trafic nominal ; prévenir starvation, duplicate storms et repair fanout non borné.
### `pre.009` — snapshots / observabilité gaps et repair
Projeter uniquement les dimensions source-neutral nécessaires : gaps détectés, pending/repaired/unresolved, activité de repair, health et compteurs checked, sans payload provider sensible.
### `pre.010` — races / shutdown hardening
Stop/fault pendant replay, coverage wait, scan HTTP, hydration, admission et persistence ; tâches orphelines, deadlines, abort+join, counters et terminalité.
Si `pre.001` retient réellement une source EARLY, insérer **une tranche dédiée avant le gate de completeness**. Ne pas la mélanger à un fix ou à une tranche de fermeture. Si aucune preuve suffisante n'existe, EARLY reste hors release sans prerelease artificielle.
### `pre.011` — completeness/security cross-layer
Canaris Worker/Transport/Common RAW/Store, dépendances, API publique, redaction, Legacy/V0/V1, non-régression des cinq familles `0.3.13` et preuves de non-confusion Worker/Backfill.
### `pre.012` — gate technique/live
Workspace complet, Clippy strict, suites ciblées, graphes/duplicates et smokes réellement accessibles. Aucun nouveau scope.
### `pre.013` — réconciliation documentaire
README/USAGE, plan, validation et architectures/références réellement affectées. Pas de CHANGELOG/ROADMAP/prompt suivant.
### `pre.014` — préparation publication
Prompt `0.3.15`, CHANGELOG, ROADMAP et fichiers mécaniques uniquement.
### `rel.001`
Publication stable mécanique après gate validé.
Le forecast peut être allongé par une tranche EARLY réellement justifiée, des fixes ou des tranches dédiées ; il ne doit jamais être compressé en mélangeant les responsabilités de fermeture.
## 11. Versionnement, deltas, commits et tags
Règles obligatoires :
```text
livraison prerelease : 0.3.14-pre.NNN
Cargo : 0.3.14-pre.N
fix : 0.3.14-pre.N.fix.M
delta : deltas/0.3.14/pre.NNN.md ou pre.NNN-fix.NNN.md
commit : v0.3.14-pre.NNN[-fix.NNN]
tag prerelease : aucun
tag stable final : v0.3.14 seulement après rel.001 validée
```
Toute prerelease non-fix synchronise `workspace.package.version`, même documentaire. Une correction strictement doc-only portée par un fix ne bump pas la version Cargo racine. Tout fichier modifié incrémente son header de version selon les règles du dépôt.
Les archives d'échange restent des deltas minimaux.
## 12. Procédure d'application et validation opérateur
Après application d'un delta technique :
```bash
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
```
Puis exécuter les tests ciblés de la tranche. Si un gate devient rouge, produire un fix strictement rattaché à la responsabilité fautive avant d'avancer.
Aucune commande non exécutée ne peut être déclarée PASS.
## 13. Validations Rust / Transport / Config / live / graphes pertinentes
Selon les couches modifiées :
```bash
cargo test -p ksp-worker-raw-transaction-ingest-lib
cargo test -p ksp-onchain-transport-lib
cargo test -p ksp-raw-transaction-lib
cargo test -p ksp-store-api
cargo test -p ksp-store-lib --no-default-features
```
Si Config/profils provider sont réellement modifiés :
```bash
cargo test -p ksp-config-lib
```
Graphes à auditer si le graphe de dépendances/features change, et à la fermeture technique :
```bash
cargo tree -p ksp-worker-raw-transaction-ingest-lib --edges normal
cargo tree -p ksp-worker-raw-transaction-ingest-lib -e features
cargo tree --duplicates
```
À la fermeture technique :
```bash
cargo test --workspace --all-targets --all-features
```
Smokes live possibles uniquement après audit `pre.001` et lorsqu'ils sont réellement provisionnés :
```text
Solana HTTP Devnet
Solana WebSocket Devnet
Yellowstone provider avec replay/from_slot si credential/tier/rétention disponibles
Helius transactionSubscribe si credential/tier disponible
blockSubscribe provider réellement accessible
Worker repair end-to-end vers Store sur environnement de test approprié
source redondante réellement composée si deux voies comparables sont disponibles
```
Un smoke indisponible est `NON EXÉCUTÉ`, pas PASS. Aucun secret n'est écrit dans une commande persistée, un log, un delta ou un fichier source.
## 14. Critères de clôture de `0.3.14`
La release peut se fermer lorsque :
```text
base multi-source 0.3.13 non régressée
gap du run possède identité/plage/bornes explicites
replay natif utilisé seulement lorsque Transport/provider le rend adressable et prouvable
coverage redondante ne vaut repair que si la plage est réellement démontrée
scan HTTP repair reste borné au run et ne devient pas Backfill
hydration de réparation repasse par Transport/Common RAW/admission/Store
skipped/missing/unavailable sont distingués sans invention de complétude
repaired et unresolved possèdent des critères explicites
reprise live n'efface jamais un unresolved gap
health policy ne masque pas une perte de coverage
backpressure/fairness restent bornés pendant repair
aucun second actor/client/retry Transport dans le Worker
aucun Worker -> Config/Job/backend physique
shutdown/fault pendant repair sans tâche orpheline ni late persistence
diagnostics redacted
EARLY absent ou réellement prouvé dans une tranche dédiée
fixtures/canaris cross-layer verts
smokes accessibles exécutés ou impossibilité qualifiée
gates workspace/clippy/tests/trees verts
documentation réconciliée
prompt 0.3.15 produit dans la dernière prerelease
```
## 15. Release suivante envisagée
`0.3.15` doit reprendre uniquement après publication stable de `0.3.14` et introduire :
```text
ksp-app-raw-transaction-ingest-desk
composition Config + Logging + Worker finalisé
sélection/supervision d'une ou plusieurs sources réellement admises
lifecycle start/stop
health et source state sûrs
rates/backpressure/reconnect/recovery/gap state
compteurs et diagnostics source-neutral
```
La Desk ne réimplémente ni discovery, hydration, déduplication, replay/repair, persistence ou logique provider. Elle reste une surface de composition/contrôle Tauri sur les APIs stables de la couche Worker/Config/Transport.
Elle doit réutiliser le gabarit Desk KSP courant : splash, fonts, style, dépendances frontend de base et tracing TypeScript des interactions significatives sans valeurs sensibles.
## 16. Instruction d'ouverture
Au début de la prochaine session :
1. vérifier que la base correspond exactement au tag stable `v0.3.13` et que `deltas/0.3.13/rel.001.md` est présent ;
2. lire les règles, le handoff `0.3.13`, l'architecture RAW acquisition et les sources Worker/Transport/Common/Store/Backfill/Config avant toute modification ;
3. réauditer les capacités actuelles Solana/Yellowstone/providers de replay, rétention et historique réellement adressable ;
4. produire `0.3.14-pre.001` avec matrice gap/replay/coverage/repair, threat model, health policy candidate, smokes accessibles, sizing, plan `035` et validation `031` ;
5. **ne pas coder de scan repair, failover/degraded policy, modification Transport/Config ni adapter EARLY avant fermeture de ce gate** ;
6. rescinder `0.3.14` immédiatement si le périmètre réel n'est pas clôturable dans une seule session.