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

v0.3.11-pre.013

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-08 21:11:52 +02:00
parent a8cabbebd5
commit 107986bf85
5 changed files with 855 additions and 5 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: 30 -->
<!-- version: 31 -->
# Changelog KSP
## 0.3.11 — Fondation runtime source-neutral du Worker RawTransaction ingest — 2026-09-08
`0.3.11` introduit `ksp-worker-raw-transaction-ingest-lib` comme premier Worker concret KSP pour l’acquisition continue de `RawTransaction`, tout en fermant volontairement la release **sans source réseau productive**. La crate consomme `ksp-worker-api`, `ksp-raw-transaction-lib` et la seule façade `ksp-store-lib`; elle ne dépend ni de Config, ni d’un Job, ni d’un backend Store physique, ni encore de `ksp-onchain-transport-lib`. Son identité stable est `raw_transaction_ingest`, ses settings bornent la capacité d’admission, la concurrence de persistence et la deadline de drain, et son `start` utilise exclusivement le runtime Tokio actif fourni par le caller.
Le runtime possède un supervisor privé, des tâches source/persistence détenues, une admission centrale `mpsc` bornée avec backpressure, la canonicalisation/assembly Common RAW, une observation key déterministe et la persistence atomique en mode `Normal`. Les outcomes distinguent insert, idempotence et tombstone purgée ; un contenu divergent devient `worker_raw_transaction_ingest.content_conflict`, les erreurs Store restent classifiées sans texte distant, et aucun provider gagnant n’est choisi implicitement. Les snapshots concrets latest-value se projettent directement sur `WorkerSnapshotSource`, utilisent séquences/compteurs checked et conservent le terminal pour les lecteurs tardifs.
Le hardening final ferme les races stop/fault, les source failures, la saturation observable, le Store lent/fautif et le shutdown borné. À l’expiration de `shutdown_drain_timeout`, le Worker ferme les admissions, abort les tâches restantes, les rejoint toutes puis publie `drain_timeout`; aucune tâche privée ne survit au terminal. Les tests externes de hardening/release verrouillent les sept codes d’erreur publics, les huit modules de production, les vingt-quatre exports crate-root, la redaction, le dependency firewall et l’absence de surface historique/Backfill/Transport/Config/backend direct.
Le gate technique final `pre.011` passe rustfmt check, audits Rust/Markdown, `cargo check --workspace`, Clippy strict, 56 tests Worker, `cargo test --workspace --all-targets --all-features`, les arbres Cargo Worker normal/features et `cargo tree --duplicates`. La réconciliation `pre.012` ajoute ensuite les README/USAGE durables du Worker et réaligne l’architecture sur l’état matériel : la fondation `0.3.11` n’a aucun adapter HTTP/WS/Yellowstone productif, aucune API publique d’enqueue/source registration et aucun replay/gap-repair live.
La trajectoire live reste découpée : `0.3.12` ouvre Yellowstone transactions/blocks/status + hydration HTTP + continuité de run, `0.3.13` ajoute WS standard/Helius/HTTP live et la convergence multi-source, puis `0.3.14` ferme le gap repair/hardening multi-source. `prompts/031-V0_3_12_START_PROMPT.md` ouvre `0.3.12` uniquement depuis le tag stable `v0.3.11`; son `pre.001` doit réauditer les surfaces Yellowstone/Solana/provider actuelles, l’injection Transport, l’hydration, le frontier, `from_slot`/ReplayInfo, les smokes accessibles et le sizing avant toute implémentation lourde.
## 0.3.10 — Lower-layer RAW Transaction commune + qualification cross-source — 2026-09-08
`0.3.10` introduit `ksp-raw-transaction-lib` comme lower-layer source-neutral commune aux producteurs `RawTransaction`. La canonicalisation RAW v1 auparavant locale à `ksp-job-backfill-lib` est extraite sans modifier les golden bytes/hash existants ; le Backfill consomme désormais cette common crate sans créer de dépendance vers un Worker. La bibliothèque construit les modèles `RawTransaction`/`RawTransactionObservation` de `ksp-store-api`, conserve l'identité canonique `(network, signature)`, borne et redacted les entrées hostiles, et reste volontairement sans Transport, Config, runtime async, Job, Worker ou backend Store physique.

4
Cargo.toml
View File

@@ -1,12 +1,12 @@
# file: Cargo.toml
# version: 516
# version: 517
[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.11-pre.12"
version = "0.3.11-pre.13"
edition = "2024"
license = "MIT"
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

4
ROADMAP.md
View File

@@ -1,5 +1,5 @@
<!-- file: ROADMAP.md -->
<!-- version: 108 -->
<!-- version: 109 -->
# Roadmap KSP
@@ -103,7 +103,7 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
- [X] `0.3.8` — `ksp-app-store-desk` V1 RAW livrée sur le gabarit KSP courant comme application Tauri read-only backend-neutral. La Desk compose Config + Logging + `ksp-store-lib`, expose health/runtime sûrs, DataTables `serverSide` pour `RawTransaction`, `RawAccountState` et leurs observations, détails bornés, provenance sûre et états de rétention/tombstone, sans SQL/backend physique/Transport dans l'application. La nouvelle inspection random-access `offset + limit + counts exacts` reste distincte de la pagination machine cursor/keyset conservée pour workers/backfills/replays. Le gate final et les builds Linux `.deb`/`.rpm` sont verts.
- [X] `0.3.9` — `ksp-worker-api` stable comme API générique et volontairement courte pour services continus : identité/kind bornés, lifecycle explicite, health/activity sûrs, stop token partagé, séquence/snapshot latest-value et `WorkerSnapshotSource` object-safe, avec dépendance Core-only et sans runtime/start-stop universel, Solana, Transport, Store, Config ou Tauri. Après freeze Worker API, l'audit `RawTransaction` a été consolidé dans une synthèse Store-centrique exhaustive séparant possibilités/support/preuve et classant HTTP, WS standard/provider, Yellowstone gRPC, blocs/slots, discovery + hydration, replay de continuité, archives et sources EARLY. Le Job Backfill historique paramétré et le Worker Ingest live start/stop sont deux producteurs indépendants du même Store ; `mainnet` est désormais l'identité KSP canonique et `mainnet-beta` un alias legacy/externe. Le handoff retient `ksp-raw-transaction-lib` comme lower-layer commune de canonicalisation RAW v1 pour `0.3.10`, sans edge Job ↔ Worker.
- [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`.
- [ ] `0.3.11` — Introduire la **fondation runtime** de `ksp-worker-raw-transaction-ingest-lib` sans source live complexe : crate/dependency firewall, settings source-neutral, handle/start-stop, lifecycle, snapshots, supervisor, bounded channels et pipeline de persistence/déduplication déterministe. Aucun protocole live n'est encore requis pour fermer cette release.
- [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`.
- [ ] `0.3.12` — Ajouter au Worker la voie **Yellowstone + hydration HTTP** : transactions/blocks/status, projection vers la common RAW, provenance sûre, `from_slot`, replay info, frontier de run et continuité propre au run, avec fixtures déterministes et smokes accessibles sans prétendre à un RAW-direct lorsque les métadonnées restent incomplètes.
- [ ] `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.
- [ ] `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é.

164
deltas/0.3.11/pre.013.md Normal file
View File

@@ -0,0 +1,164 @@
<!-- file: deltas/0.3.11/pre.013.md -->
<!-- version: 1 -->
# Delta `0.3.11-pre.013` — préparation de publication
## 1. Base requise
```text
0.3.11-pre.012
```
Le gate opérateur de `pre.012` est vert sur rustfmt check, audits Rust/Markdown, `cargo check --workspace`, 56 tests Worker et doc-tests.
## 2. Objectif
`pre.013` est la dernière prerelease de préparation de publication de `0.3.11`.
Conformément au couloir KSP de fermeture, elle modifie uniquement :
```text
prompt de démarrage 0.3.12
CHANGELOG.md
ROADMAP.md
Cargo.toml racine mécanique
delta pre.013
```
Aucun README, USAGE, plan, validation, architecture, code, test, Config ou manifest de crate n'est modifié.
## 3. Version workspace
La prerelease non-fix synchronise Cargo :
```text
0.3.11-pre.12
->
0.3.11-pre.13
```
## 4. Préparation de la release suivante
Le nouveau prompt :
```text
prompts/031-V0_3_12_START_PROMPT.md
```
ouvre `0.3.12` exclusivement depuis le futur stable :
```text
v0.3.11
```
Sa mission est bornée à Yellowstone + hydration HTTP + continuité propre au run du Worker. Son `pre.001` impose avant codage :
```text
audit stable réel 0.3.11
audit Yellowstone/Solana/provider courant
matrice Transaction/Status/Block/BlockMeta/Slot/from_slot/ReplayInfo
architecture d'injection Transport sans Worker -> Config
stratégie hydration et provenance
frontier/reconnect/replay semantics
threat model live
smokes réellement accessibles
graphe Cargo cible
sizing et rescission éventuelle
plan 033 + validation 029
```
## 5. CHANGELOG
`CHANGELOG.md` reçoit l'entrée de synthèse `0.3.11` :
```text
fondation Worker source-neutral
admission/persistence/snapshots/shutdown hardening
dependency firewall
absence volontaire de source live dans 0.3.11
gate technique final réel
handoff 0.3.12-0.3.14
prompt 031
```
## 6. ROADMAP
L'entrée `0.3.11` passe de `[ ]` à `[X]` et décrit l'état effectivement livré. Les entrées `0.3.12`–`0.3.14` restent ouvertes et conservent leur découpage live existant.
## 7. Fichiers ajoutés
```text
prompts/031-V0_3_12_START_PROMPT.md
deltas/0.3.11/pre.013.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
docs/**
crates/**
config/**
tests/**
```
Hormis le nouveau prompt situé sous `prompts/`, aucun autre prompt n'est modifié.
## 11. Validations exécutées pendant l'assemblage
Sur l'état exact destiné à l'archive :
```text
General Rust rule audit: clean
Rust export completeness audit: 0 candidate(s)
KSP workspace Rust rule audit: clean
Markdown table audit: clean (340 table(s), 797 file(s))
```
La revue de diff confirme également :
```text
2 fichiers ajoutés
3 fichiers modifiés
0 fichier supprimé
aucun changement README/docs/crates/config/tests
prompt 031 : 16 sections normatives présentes
```
## 12. Validations non exécutées dans l'environnement d'assemblage
L'environnement d'assemblage ne dispose pas de Cargo/Rustc. Les contrôles Cargo minimum de la prerelease restent opérateur :
```bash
cargo fmt --all -- --check
cargo check --workspace
```
Aucun test ou Clippy lourd n'est requis par le contenu de cette tranche de publication, puisqu'aucun code/test/dépendance/feature n'est modifié.
## 13. Décisions prises
- `0.3.11` est prêt pour une publication stable mécanique après validation de `pre.013` ;
- `0.3.12` ne commence qu'après `0.3.11-rel.001` et le tag stable `v0.3.11` ;
- le prompt suivant n'autorise aucun codage Yellowstone avant son `pre.001` d'audit/sizing ;
- aucune correction d'un couloir antérieur n'est absorbée dans cette préparation de publication.
## 14. Questions ouvertes
```text
aucune question bloquante pour la préparation de publication 0.3.11
```

674
prompts/031-V0_3_12_START_PROMPT.md Normal file
View File

@@ -0,0 +1,674 @@
<!-- file: prompts/031-V0_3_12_START_PROMPT.md -->
<!-- version: 1 -->
# Prompt de démarrage `0.3.12` — Yellowstone + hydration HTTP + continuité de run du Worker `RawTransaction`
## 1. Identité de la release et base exacte requise
Ouvrir **uniquement** `0.3.12` depuis la release stable/taggée :
```text
v0.3.11
```
La base de travail fournie par l'opérateur est autoritaire sur les souvenirs de session, snippets, anciennes archives et deltas intermédiaires. Avant toute modification, vérifier au minimum :
```text
workspace.package.version = 0.3.11
deltas/0.3.11/rel.001.md présent
crates/ksp-worker-raw-transaction-ingest-lib présent et documenté
crates/ksp-worker-raw-transaction-ingest-lib sans source réseau productive dans le stable 0.3.11
crates/ksp-raw-transaction-lib présent et stable
crates/ksp-onchain-transport-lib présent avec moteur Yellowstone générique
crates/ksp-store-lib présent comme seule façade Store du Worker
ksp-job-backfill-lib indépendant du Worker
```
Release ouverte :
```text
0.3.12
```
Première livraison attendue :
```text
0.3.12-pre.001
```
`pre.001` est obligatoirement un gate de **lecture + audit interne/externe + brainstorming + sizing + planification**. Il ne commence pas directement l'intégration Yellowstone productive. Si le périmètre réel n'est pas clôturable dans une seule session ou si une tranche intermédiaire paraît dépasser environ 15–20 minutes de travail effectif, rescinder la release avant l'implémentation lourde.
## 2. Mission et résultat attendu
### 2.1 Mission de `0.3.12`
Étendre la fondation source-neutral de :
```text
ksp-worker-raw-transaction-ingest-lib
```
avec la première famille live productive, centrée sur **Yellowstone gRPC + hydration HTTP** et la continuité propre au run du Worker.
Résultat cible à réauditer pendant `pre.001` :
```text
edge Worker -> ksp-onchain-transport-lib seulement si réellement nécessaire
adapter Yellowstone transaction/block/status vers le pipeline privé existant
réutilisation du moteur Yellowstone générique existant
projection fidèle du transaction wire vers ksp-raw-transaction-lib
hydration HTTP lorsque le matériau Yellowstone ne suffit pas au RAW v1 complet
provenance sûre de la route réellement observée
source tasks intégrées au supervisor existant
frontier de run live explicite et borné
from_slot / replay info exploités uniquement pour continuité du run
reconnexion distinguée du replay/repair
snapshots/health enrichis seulement par dimensions réellement prouvées
fixtures déterministes cross-layer
smokes live uniquement sur providers/réseaux réellement accessibles
```
`0.3.12` ne doit pas ouvrir les voies WS standard, Helius `transactionSubscribe`, HTTP live block polling multi-source complet ni le gap repair multi-source final ; ces responsabilités restent réparties sur `0.3.13` et `0.3.14`.
### 2.2 Principe de correction RAW à préserver
Le pipeline durable reste :
```text
source live
-> matériau source/protocole
-> hydration si nécessaire
-> ksp-raw-transaction-lib
-> RawTransaction + RawTransactionObservation
-> ksp-store-lib
```
Aucune source ne doit inventer un RAW complet à partir d'un signal incomplet.
Décision conservative déjà qualifiée :
```text
Yellowstone Transaction/Block -> transaction wire fidèle + métadonnées disponibles
RAW v1 complet -> hydration HTTP tant que block_time/meta parity n'est pas prouvée suffisante
```
Si `pre.001` démontre qu'un sous-ensemble Yellowstone peut désormais produire un RAW v1 direct sans hydration, cette évolution doit être prouvée par fixture/canari byte-exact avant de modifier cette décision.
## 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.11`
Lire intégralement :
```text
docs/plans/032-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION_PLAN.md
docs/validation/028-V0_3_11_RAW_TRANSACTION_INGEST_WORKER_FOUNDATION.md
crates/ksp-worker-raw-transaction-ingest-lib/Cargo.toml
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 fondation stable est une contrainte, pas un brouillon à remplacer.
### 3.3 Acquisition RAW et qualification cross-source
Lire intégralement :
```text
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
docs/plans/031-V0_3_10_RAW_TRANSACTION_INGEST_PLAN.md
docs/validation/027-V0_3_10_RAW_TRANSACTION_INGEST.md
crates/ksp-raw-transaction-lib/README.md
crates/ksp-raw-transaction-lib/USAGE.md
crates/ksp-raw-transaction-lib/src/
crates/ksp-raw-transaction-lib/tests/
```
Porter une attention particulière aux sections de `011` concernant :
```text
Yellowstone transactions / transactions_status / blocks / blocks_meta / slots
from_slot
SubscribeReplayInfo / continuity snapshots
hydration HTTP
reconnexion != replay
Worker continuity repair != campagne historique
qualification transaction wire Legacy/V0/V1
limites de la preuve RAW-direct Yellowstone actuelle
```
### 3.4 Transport Yellowstone et HTTP existants
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/grpc_*.rs
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
crates/ksp-onchain-transport-lib/src/rpc_blocks.rs
crates/ksp-onchain-transport-lib/tests/
```
Réutiliser le moteur générique existant ; ne pas créer un second client Yellowstone, un actor gRPC Worker parallèle ou un SDK provider.
Les primitives HTTP observées existantes à réauditer incluent notamment :
```text
get_transaction_observed
get_block_observed
```
L'hydration doit conserver la provenance réellement observée du winner HTTP plutôt qu'un endpoint supposé.
### 3.5 Store, Worker API et Config comme frontières
Lire au minimum :
```text
crates/ksp-store-lib/README.md
crates/ksp-store-lib/USAGE.md
crates/ksp-store-lib/src/
crates/ksp-worker-api/README.md
crates/ksp-worker-api/USAGE.md
crates/ksp-worker-api/src/
crates/ksp-config-lib/README.md
crates/ksp-config-lib/USAGE.md
crates/ksp-config-lib/src/
```
Le Worker continue d'écrire via `ksp-store-lib` uniquement.
`ksp-config-lib` reste propriétaire des profils, endpoints, providers/protocoles, secrets et activation/composition. **Le Worker ne lit jamais Config ou l'environnement directement.** L'éventuelle adaptation Config de `0.3.12` doit être décidée après audit de l'injection de ressources runtime ; ne pas créer automatiquement un edge Worker -> Config.
## 4. Sources externes normatives et fraîcheur à réauditer
La fraîcheur est importante dans `0.3.12`. `pre.001` doit consulter les sources primaires courantes avant toute décision d'API ou de capability :
```text
Yellowstone gRPC upstream : proto geyser + solana-storage + README + changelog
Solana JSON-RPC officiel : getTransaction / getBlock et champs nécessaires à l'hydration
providers Yellowstone réellement envisagés/accessibles : documentation endpoint/auth/replay/from_slot
versions stables actuelles des crates externes touchées
```
Réauditer en particulier :
```text
shape courante SubscribeRequest/from_slot
SubscribeReplayInfo et sémantique de replay exposée par le moteur/proto courant
Transaction / TransactionStatus / Block / BlockMeta wire actuel
profondeur et disponibilité réelle du replay provider-specific
réseaux réellement servis
mode d'authentification actuel
limitations/tier actuels
```
Ne pas recopier comme vérité actuelle les prix, limites ou profondeurs de replay historiques présents dans `docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`. Cette architecture conserve les décisions KSP ; les paramètres provider temporels doivent être revérifiés.
Préférer les sources primaires. Aucun SDK provider n'est ajouté pour une simple compatibilité Yellowstone standard.
## 5. État validé à préserver
### 5.1 Fondation Worker stable
Le stable `0.3.11` possède déjà :
```text
RawTransactionIngestSettings bornés
RawTransactionIngestWorker::start
RawTransactionIngestHandle
request_stop idempotent
terminal future
supervisor privé
JoinSet sources/persistences privés
mpsc central borné
backpressure observée
canonicalisation/assembly Common RAW
persistence atomique Store mode Normal
content conflict terminal
snapshots concrete + WorkerSnapshotSource
source/store/counter/drain faults classifiés
shutdown deadline + abort/join avant terminal timeout
```
`0.3.12` étend cette fondation ; il ne crée pas un second lifecycle, un second pipeline d'admission ou un second système de snapshots.
### 5.2 Dependency firewall
État `0.3.11` :
```text
Worker -> ksp-core-lib
Worker -> ksp-logging-lib
Worker -> ksp-raw-transaction-lib
Worker -> ksp-store-lib default-features=false
Worker -> ksp-worker-api
Worker -> sha2
Worker -> tokio
Worker -X-> ksp-onchain-transport-lib
Worker -X-> ksp-config-lib
Worker -X-> ksp-job-backfill-lib
Worker -X-> backend Store physique
```
`0.3.12` peut matérialiser l'edge `Worker -> ksp-onchain-transport-lib` si `pre.001` confirme qu'il est la frontière correcte pour la source Yellowstone/hydration. Aucun autre edge interdit n'est ouvert par simple commodité.
### 5.3 Identité et persistence
```text
RawTransaction identity = (network, signature)
mainnet = identité KSP canonique
mainnet-beta = alias legacy/externe seulement
```
La convergence Store reste : une entité canonique + observations/provenances distinctes. Un contenu canonique divergent reste `content_conflict`, jamais une règle « premier provider gagne » ou « dernier provider gagne ».
### 5.4 Séparation Job / Worker
```text
Job Backfill = historique paramétré, borné, terminable
Worker Ingest = acquisition continue start/stop, sans requête historique métier
```
Le Worker peut utiliser `from_slot`/replay pour restaurer **sa propre continuité de run**. Cela ne l'autorise pas à recevoir un scope historique arbitraire du caller ni à appeler `ksp-job-backfill-lib`.
## 6. Décisions acquises et questions réellement ouvertes
### 6.1 Décisions acquises
Conserver :
```text
un seul runtime Worker existant
un seul pipeline admission -> common RAW -> Store
sources réseau privées au supervisor
aucune API publique enqueue arbitraire
Transport générique réutilisé, aucun client Yellowstone dupliqué
HTTP est une capability normale du Worker pour hydration/repair live
Config/secrets restent hors Worker
provenance HTTP = route réellement observée
channels bornés
aucun drop silencieux
reconnect gRPC != replay/continuité restaurée
from_slot/replay du Worker limité à son frontier de run
Job et Worker indépendants
pas de RAW-direct Yellowstone complet sans preuve nouvelle
```
### 6.2 Questions à fermer dans `pre.001`
Auditer avant codage :
```text
forme exacte d'injection des ressources Transport dans RawTransactionIngestWorker::start ou une API voisine
si la surface publique actuelle doit évoluer ou si un objet runtime/source bundle privé suffit
ownership exact des source ids/capabilities/priorités
rôle de Config dans 0.3.12 et direction de dépendance correcte
quelles familles Yellowstone sont P0 réellement productives : transactions, blocks, status, blocks_meta, slots
stratégie d'hydration transaction vs block
clé de coalescence entre signal Yellowstone et résultat HTTP hydraté
provenance finale quand signal et hydration proviennent de transports/providers distincts
frontier exact : slot observed, slot persisted, contiguous slot, ou plusieurs dimensions
sémantique exacte de from_slot au démarrage/reconnect
traitement de SubscribeReplayInfo et absence de preuve provider
états source health/degraded/unhealthy/faulted réellement nécessaires
politique lorsque l'hydration renvoie missing/not-available temporaire
bornes de retry/backoff et ownership entre Transport et Worker
stop pendant reconnect/replay/hydration
besoin de nouveaux compteurs/snapshot fields sans fuite de matériel
smokes live réellement accessibles et secrets opérateur disponibles
```
Ne pas figer ces réponses dans l'API avant le gate `pre.001`.
## 7. Objectifs/livrables et hors périmètre
### 7.1 Livrables attendus de `0.3.12`
Sous réserve du sizing `pre.001` :
```text
adapter(s) Yellowstone productifs dans le Worker
projection Transport DTO -> common wire/material dans le producer Worker
hydration HTTP explicite lorsque requise
source tasks Yellowstone intégrées au supervisor existant
provenance sûre source + hydration
frontier de run et continuité bornée
from_slot/replay info exploités sans campagne historique
snapshots/health adaptés seulement si nécessaire
fixtures déterministes transaction/block/status/hydration
canaris de dependency firewall et redaction
smokes live opt-in sur accès réellement disponible
plan 0.3.12
validation 0.3.12
README/USAGE réconciliés en fin de release
```
Le `USAGE.md` reste version-neutral.
### 7.2 Hors périmètre de `0.3.12`
```text
WS logsSubscribe productif
WS blockSubscribe productif dans le Worker
Helius transactionSubscribe productif
HTTP live block polling multi-source complet
convergence simultanée de toutes les familles 0.3.13
gap repair multi-source complet 0.3.14
source redondante/failover final
EARLY shreds/deshred/feed vendor-specific
Desk d'ingestion 0.3.15
Backfill multi-source 0.3.16
D2 STRUCTURAL
backend Store direct
nouvelle migration Store sauf défaut réellement démontré et release rescindée si nécessaire
```
Si une responsabilité de `0.3.13+` devient indispensable pour rendre Yellowstone correct, `pre.001` doit expliquer le couplage et rescinder la trajectoire avant développement lourd.
## 8. Contraintes sécurité/API/architecture spécifiques
Le runtime live doit garantir au minimum :
```text
aucune URL/token/header/API key dans Debug/Display/snapshot/error public
aucun payload transaction/meta/log provider dans diagnostics
aucun remote status/message arbitraire recopié dans Error context
source ids/codes bornés et non secrets
provenance safe sans endpoint secret
frontier/replay state sans signature/payload
counter arithmetic checked/non-wrapping
queues bornées
aucun task leak après terminal
stop préemptif pendant connect/reconnect/hydration/replay
pas de double retry incontrôlé Transport + Worker
pas de busy loop en indisponibilité provider
pas de claim de continuité si un gap n'est pas prouvé réparé
```
L'hydration doit être explicitement classifiée :
```text
signal incomplet -> pending hydration
hydration complète -> admission RAW
missing temporaire -> état/retry borné défini par la tranche
matériau contradictoire -> fault/content conflict selon frontière réellement concernée
stop -> aucune nouvelle hydration/admission après frontière de stop
```
Le tracing reste via `ksp-logging-lib` et n'expose jamais la signature, le raw body, la meta, l'URL ou le credential.
## 9. Première mission `pre.001` — audit/sizing obligatoire
`pre.001` doit produire **avant toute implémentation lourde** :
1. vérification exacte de la base stable `v0.3.11` et du `rel.001` ;
2. lecture complète des sources internes listées ci-dessus ;
3. inventaire réel des surfaces Worker/Transport/Common RAW/Store/Config ;
4. audit externe courant Yellowstone/Solana/provider et versions de crates concernées ;
5. matrice exacte `Transaction / TransactionStatus / Block / BlockMeta / Slot / from_slot / ReplayInfo` : matériau disponible, gaps RAW, besoin d'hydration, preuve actuelle ;
6. architecture d'injection des ressources Transport sans Worker -> Config ni API publique enqueue ;
7. modèle de frontier/continuité du run et distinction reconnect/replay/repair ;
8. stratégie d'hydration HTTP et provenance cross-transport ;
9. threat model live : secrets, remote errors, saturation, duplicate signals, retry storms, reconnect races, stop during hydration/replay, stale frontier ;
10. inventaire des smokes réellement accessibles et conditions opérateur ;
11. graphe Cargo cible et features minimales ;
12. sizing de chaque tranche sous le budget 15–20 minutes ;
13. décision explicite : `0.3.12` reste clôturable dans une session ou doit être rescindée avant codage ;
14. création/révision des documents de release.
Documents attendus :
```text
docs/plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md
docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.md
```
Le delta `pre.001` consigne les décisions fermées, les questions reportées, les dépendances réellement requises, les gates live possibles et le forecast recalibré.
Critère de sortie : la première tranche technique doit pouvoir être implémentée sans décider simultanément l'API source, l'hydration, le frontier et la stratégie de replay pendant le codage.
## 10. Prévision souple initiale des prereleases
Cette prévision est un **point de départ à recalibrer par `pre.001`**, pas un engagement de numérotation.
### `pre.001` — audit / brainstorming / sizing
Base stable, matrice Yellowstone, fraîcheur provider/proto, injection Transport, hydration, frontier, replay semantics, threat model, smokes accessibles, plan/validation et décision de maintien/rescission.
### `pre.002` — dependency/source contract
Matérialiser uniquement les edges/types runtime réellement nécessaires, en particulier l'edge Worker -> Transport si confirmé, sans encore ouvrir toutes les familles Yellowstone.
### `pre.003` — adapter Yellowstone transaction
Brancher la première tâche source `transactions`, projeter le transaction wire vers Common et prouver les gaps qui imposent l'hydration. Aucun RAW-direct non prouvé.
### `pre.004` — hydration HTTP transaction
Fermer signal Yellowstone -> `get_transaction_observed` -> common RAW -> admission/persistence, avec provenance sûre et comportement missing/error borné.
### `pre.005` — blocks / block metadata
Ajouter les formes Yellowstone block/block_meta réellement nécessaires, réutiliser la même canonicalisation et comparer leur matériau à l'hydration HTTP sans dupliquer le pipeline.
### `pre.006` — transaction status + source supervision
Intégrer `transactions_status` uniquement pour le rôle réellement démontré (discovery/status/hydration), source health et failures sans exposer de matériau provider.
### `pre.007` — frontier de run + from_slot / replay info
Matérialiser la continuité propre au run : frontier explicite, reconnexion distincte du replay, `from_slot` et replay info utilisés uniquement lorsqu'ils sont réellement supportés/provables.
### `pre.008` — races/retry/backpressure hardening live
Stop pendant connect/reconnect/hydration/replay, saturation, duplicate signals, retry ownership, Store slow/fault et absence de tâches orphelines. Scinder si nécessaire.
### `pre.009` — fixtures/cross-layer completeness
Canaris déterministes exacts sur les familles Yellowstone admises, hydration, provenance, common RAW, API root, dependency firewall et security scans.
### `pre.010` — gate live/technique final
Smokes accessibles si réellement configurés, workspace complet, Clippy strict, suites ciblées, arbres Cargo Worker normal/features et duplicate tree. Aucun nouveau scope fonctionnel.
### `pre.011` — réconciliation documentaire
README/USAGE, plan, validation et architecture/références réellement affectées. Aucun CHANGELOG/ROADMAP/prompt suivant.
### `pre.012` — préparation de publication
Prompt `0.3.13`, CHANGELOG, ROADMAP et fichiers mécaniques uniquement.
### `rel.001`
Publication stable mécanique sans rattrapage.
Si `pre.001` conclut que les familles Yellowstone + hydration + continuité dépassent une session, rescinder `0.3.12` avant `pre.002` au lieu de forcer ce forecast.
## 11. Versionnement, deltas, commits et tags
Règles obligatoires :
```text
livraison prerelease : 0.3.12-pre.NNN
Cargo : 0.3.12-pre.N
fix code/runtime : 0.3.12-pre.N.fix.M
fix doc-only : ne bump pas Cargo
delta : deltas/0.3.12/pre.NNN.md ou pre.NNN-fix.NNN.md
commit : v0.3.12-pre.NNN[-fix.NNN]
tag prerelease : aucun
tag stable final : v0.3.12 seulement après rel.001 validée
```
Toute nouvelle prerelease non-fix synchronise `workspace.package.version`, même documentaire. 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 et conserver les logs opérateur réels. Une commande non lancée n'est jamais déclarée PASS.
Si un gate révèle un défaut, créer un fix appartenant strictement à la responsabilité de la tranche fautive. Ne pas absorber un défaut runtime dans le couloir documentaire ou publication.
## 13. Validations Rust / Transport / live / graphes pertinentes
À partir de l'activation Transport dans le Worker, le gate cible inclut progressivement :
```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-lib
cargo test -p ksp-worker-api
```
Selon les changements Config réellement retenus :
```bash
cargo test -p ksp-config-lib
```
Graphes à auditer lorsque l'edge Transport ou ses features sont matérialisés :
```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
```
Les smokes live sont **opt-in** et ne lisent jamais de secrets depuis le code/source. Le prompt `pre.001` doit déterminer ceux qui sont réellement accessibles. Une incapacité de tier/provider doit être documentée comme telle, pas transformée en fausse preuve PASS.
## 14. Critères de clôture de `0.3.12`
La release peut se fermer lorsque, sur la base réellement obtenue :
```text
fondation Worker 0.3.11 préservée sans second runtime
edge Transport minimal et justifié
au moins les familles Yellowstone retenues par pre.001 intégrées productivement
projection transaction wire -> common prouvée
hydration HTTP appliquée partout où le RAW complet l'exige
aucun RAW-direct Yellowstone revendiqué sans preuve byte/semantic exacte
provenance source/hydration sûre
frontier de run explicite et borné
reconnect distinct de replay/continuité
from_slot/replay info utilisés sans transformer le Worker en moteur historique
stop/fault/backpressure pendant tâches live durcis
aucune URL/token/remote payload dans diagnostics
Store uniquement via ksp-store-lib
aucun edge Worker -> Config/Job/backend physique
fixtures et canaris cross-layer verts
smokes accessibles exécutés ou blocage provider/tier explicitement qualifié
gates workspace/clippy/tests/trees verts
README/USAGE/plan/validation réconciliés
prompt 0.3.13 produit dans la dernière prerelease
```
## 15. Release suivante envisagée
`0.3.13` doit reprendre uniquement après publication stable de `0.3.12` et réauditer la mission :
```text
WS logsSubscribe + HTTP hydration
WS blockSubscribe direct sur le sous-ensemble déjà qualifié
Helius transactionSubscribe + hydration
HTTP live block polling
convergence simultanée multi-source
observations multiples/coalescence
backpressure et content conflict sous sources concurrentes
```
Le gap repair/hardening multi-source final reste `0.3.14`.
## 16. Instruction d'ouverture
Au début de la prochaine session :
1. vérifier que la base correspond exactement au tag stable `v0.3.11` et que `deltas/0.3.11/rel.001.md` est présent ;
2. lire les règles, le handoff `0.3.11`, l'architecture RAW acquisition et les sources Worker/Transport/Common/Store avant toute modification ;
3. réauditer les sources Yellowstone/Solana/provider actuelles et les versions de dépendances réellement concernées ;
4. produire `0.3.12-pre.001` avec matrice Yellowstone, architecture d'hydration/frontier, threat model, sizing, plan `033` et validation `029` ;
5. **ne pas ajouter l'edge Transport au Worker, ne pas coder une source Yellowstone productive et ne pas modifier Config avant fermeture de ce gate** ;
6. rescinder `0.3.12` immédiatement si le périmètre réel n'est pas clôturable dans une seule session.