khadhroony-solana-project/prompts/032-V0_3_13_START_PROMPT.md

<!-- file: prompts/032-V0_3_13_START_PROMPT.md -->
<!-- version: 1 -->

# Prompt de démarrage `0.3.13` — WS standard / Helius / HTTP live + convergence multi-source du Worker `RawTransaction`

## 1. Identité de la release et base exacte requise

Ouvrir **uniquement** `0.3.13` depuis la release stable/taggée :

```text
v0.3.12
```

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.12
deltas/0.3.12/rel.001.md présent
crates/ksp-worker-raw-transaction-ingest-lib présent avec source Yellowstone productive
ksp-worker-raw-transaction-ingest-lib -> ksp-onchain-transport-lib matérialisé
ksp-worker-raw-transaction-ingest-lib sans dépendance Config/Job/backend Store direct
ksp-raw-transaction-lib présent comme Common RAW source-neutral
ksp-store-lib reste la seule façade Store du Worker
moteur WS standard/Helius existant dans ksp-onchain-transport-lib
getTransaction/getBlock observed existants dans ksp-onchain-transport-lib
```

Release ouverte :

```text
0.3.13
```

Première livraison attendue :

```text
0.3.13-pre.001
```

`pre.001` est obligatoirement un gate de **lecture + audit interne/externe + brainstorming + sizing + planification**. Il ne commence pas directement les sources WS/Helius/HTTP polling ni la transformation de `RawTransactionIngestRuntimeResources` en collection multi-source. 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.13`

Étendre la verticale `0.3.12` avec les voies live complémentaires déjà qualifiées par l'architecture :

```text
WS standard logsSubscribe + hydration HTTP
WS standard blockSubscribe
Helius transactionSubscribe + hydration HTTP
HTTP live polling par slots/blocs
convergence simultanée multi-source vers le pipeline central existant
observations multiples pour une même RawTransaction
coalescence/déduplication bornée avant hydration/admission
content conflict explicite si une même identité produit un contenu canonique divergent
backpressure et source health sous concurrence multi-source
```

Le résultat visé est un Worker capable de superviser plusieurs sources live indépendantes **sans second actor Transport**, sans lire Config lui-même et sans transformer la convergence en stratégie `first-provider-wins` silencieuse.

### 2.2 Pipeline durable à préserver

Toutes les sources convergent vers le même cœur :

```text
source live
    -> signal ou matériau source/protocole
    -> hydration si le RAW complet n'est pas prouvé
    -> ksp-raw-transaction-lib
    -> RawTransaction + RawTransactionObservation
    -> admission centrale Worker
    -> ksp-store-lib
```

Décisions déjà acquises :

```text
logsSubscribe                       -> discovery/signature -> getTransaction hydration
Helius transactionSubscribe         -> matériau riche mais hydration tant que blockTime/version manquent
blockSubscribe full/base64          -> RAW-direct uniquement sur le sous-ensemble déjà prouvé par fixtures
HTTP polling                        -> getSlot/bornes -> getBlock observed -> transactions -> Common RAW
même identité + même contenu        -> idempotence + observations distinctes utiles
même identité + contenu divergent   -> content conflict explicite
```

Aucune source ne doit contourner Common RAW ou la façade Store.

## 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.12`

Lire intégralement :

```text
docs/plans/033-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY_PLAN.md
docs/validation/029-V0_3_12_YELLOWSTONE_HYDRATION_CONTINUITY.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 verticale Yellowstone/hydration/frontier est une base à préserver, pas un prototype à remplacer.

### 3.3 Architecture RAW et convergence

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
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
observations multiples ≠ identité RawTransaction
même identité + contenu divergent = conflit explicite
capabilities orthogonales aux producteurs
WS logsSubscribe
WS blockSubscribe
Helius transactionSubscribe
HTTP getSlot/getBlock live polling
provenance observed
reconnect WS != replay adressable
continuité multi-source finale encore reportée à 0.3.14
```

### 3.4 Transport WS / HTTP / Helius existant

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/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
nouveau socket WebSocket bas niveau
client Helius parallèle
client reqwest direct
reconnect/resubscribe actor concurrent
SDK provider
```

### 3.5 Config et secrets

Lire :

```text
crates/ksp-config-lib/src/transport.rs
config/transport*.json
config/schema/*transport*.json
.env.example
```

Config reste le seul propriétaire des endpoints, profils, capabilities et secrets. En particulier, si Helius est activé pour cette release, réutiliser exclusivement le secret Config déjà défini pour Helius ; le Worker ne lit jamais l'environnement et ne reçoit jamais une clé API comme payload métier.

## 4. Sources externes normatives et fraîcheur à réauditer

Au début de `pre.001`, réauditer les surfaces courantes à partir des sources primaires réellement actuelles :

```text
Solana RPC/WebSocket documentation
  logsSubscribe
  blockSubscribe
  getSlot / getBlocks / getBlocksWithLimit / getBlock
  commitment et maxSupportedTransactionVersion

Helius documentation officielle
  transactionSubscribe
  filtres/options réellement supportés
  Mainnet/Devnet disponibles
  tier/quota/rate limits actuels
  champs blockTime/version réellement présents ou absents

crates/projets primaires réellement concernés
  versions stables courantes
  features nécessaires
```

Ne pas figer dans le plan une limite provider historique sans la revalider. Une différence entre documentation externe actuelle et surface KSP existante devient un point d'audit explicite, pas une permission de contourner Transport.

## 5. État validé à préserver

`0.3.12` fournit déjà :

```text
Worker concret start/stop + supervisor
admission centrale mpsc bornée
persistence Store atomique/idempotente
Common RAW Legacy/V0/V1
une source Yellowstone caller-composed
Transaction / TransactionStatus / Block -> hydration transactionnelle
BlockMeta / Slot -> continuity-only
coalescence bornée network/signature/commitment
getTransaction observed
processing frontier run-local
source state Active/Reconnecting/Closing/Closed/Failed
compteurs reconnect/replay-attempt/continuity-gap
fault sur gap de rétention prouvé
shutdown borné + abort/join
cross-layer dependency/security canaries
```

Frontières non négociables :

```text
Worker -> Config interdit
Worker -> Job Backfill interdit
Worker -> backend Store physique interdit
Transport -> Common RAW interdit
Common RAW -> Transport interdit
pas d'URL/token/provider payload dans snapshot/debug/error
pas de checkpoint persistant de processing frontier
pas de campagne historique arbitraire dans le Worker
```

Le gate `0.3.12` a aussi prouvé live HTTP Devnet et WebSocket Devnet keyless ; il n'a pas prouvé live Yellowstone ni un Worker end-to-end avec Store. Ne pas transformer ces non-preuves en hypothèses acquises.

## 6. Décisions acquises et questions réellement ouvertes

### 6.1 Décisions acquises

```text
une RawTransaction est identifiée par (network, signature)
la provenance appartient aux observations, pas à l'identité canonique
plusieurs sources peuvent produire plusieurs observations du même RAW
content conflict reste terminal/explicite, jamais first-provider-wins silencieux
logsSubscribe nécessite hydration
Helius transactionSubscribe nécessite hydration tant que son enveloppe reste incomplète pour RAW v1
blockSubscribe direct reste limité au sous-ensemble réellement qualifié
HTTP polling est une source live valide s'il suit uniquement le frontier du run courant
WS reconnect/resubscribe n'est pas un replay adressable
repair de gap multi-source final appartient à 0.3.14
```

### 6.2 Questions à fermer par `pre.001`

```text
forme exacte de RawTransactionIngestRuntimeResources multi-source
identité/source key interne commune aux sources live
activation simultanée vs priorités/fallback : sémantique exacte
coalescence cross-source avant ou après hydration selon matériau disponible
comment conserver plusieurs observations sans dupliquer la canonicalisation
blockSubscribe : sous-ensembles Legacy/V0/V1 réellement directs aujourd'hui
HTTP polling : borne initiale, cadence, slot skip et ownership du timer
source health individuel vs agrégation Worker publique
limites exactes de pending/coalescence par source et globales
Helius : profils/tier réellement testables avec les comptes opérateur disponibles
```

Aucune de ces questions ne doit être tranchée par un ajout opportuniste pendant le codage.

## 7. Objectifs/livrables et hors périmètre

### 7.1 Livrables cibles

Sous réserve du sizing `pre.001` :

```text
contrat runtime resources réellement multi-source et borné
source WS logsSubscribe productive + hydration
source WS blockSubscribe productive
source Helius transactionSubscribe productive + hydration
source HTTP live block polling productive
convergence vers la même admission/persistence centrale
coalescence et observation semantics cross-source
source health/backpressure/faults cohérents
fixtures déterministes cross-source
smokes live uniquement lorsqu'ils sont réellement accessibles
README/USAGE/architecture réconciliés à la fin
```

### 7.2 Hors périmètre `0.3.13`

```text
gap repair multi-source complet
replay historique arbitraire
appel automatique au Backfill
checkpoint durable Worker
source archive/historical provider
EARLY/pre-execution/shreds
nouveau SDK provider
nouveau backend Store ou migration Store
nouvelle Desk d'ingestion
extension du Job Backfill
```

Ces éléments appartiennent à `0.3.14+` ou `0.3.16` selon la roadmap.

## 8. Contraintes sécurité/API/architecture spécifiques

La convergence multi-source doit rester bornée :

```text
aucune Vec/Map de pending non bornée
aucun task spawn non détenu
aucun retry loop Worker redondant avec Transport
aucune queue par provider sans borne explicite
aucun drop silencieux sous saturation
aucun changement de source qui efface une provenance déjà acquise
```

La sémantique de conflit reste :

```text
même identité + même canonical RAW
    -> idempotence
    -> observation supplémentaire si sa clé est distincte

même identité + canonical RAW divergent
    -> content conflict explicite
    -> arrêt/fault selon contrat Worker existant
```

Le tracing ne doit jamais inclure :

```text
signature brute
transaction/meta bytes
logs provider
URL endpoint
API key/x-token
filtres Helius sensibles
remote error text non borné
```

Toute surface publique ajoutée doit être justifiée par un consumer réel. Préférer les types privés/crate-private et les snapshots source-neutral aux DTO provider-specific publics.

## 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.12` et de `deltas/0.3.12/rel.001.md` ;
2. lecture complète des sources internes listées ci-dessus ;
3. inventaire exact des acteurs/sessions/facades WS standard, Helius et HTTP existants ;
4. audit externe courant Solana/Helius et versions de crates réellement concernées ;
5. matrice par source : signal/material, RAW-direct ou hydration, provenance, reconnect, network, tier/preuve live ;
6. architecture cible de `RawTransactionIngestRuntimeResources` multi-source sans Worker -> Config ;
7. stratégie de source identity, source lifecycle et agrégation health ;
8. stratégie de coalescence cross-source et de production d'observations multiples ;
9. stratégie HTTP polling live bornée depuis le démarrage du run, sans campagne historique ;
10. threat model : duplicate storms, source skew, provider disagreement, hydration fanout, reconnect storms, polling drift, slow Store, stop/fault concurrent ;
11. inventaire des smokes réellement accessibles avec les ressources opérateur ;
12. graphes Cargo/features cibles et éventuels changements Config strictement nécessaires ;
13. sizing de chaque tranche sous le budget 15–20 minutes ;
14. décision explicite : maintien de `0.3.13` ou rescission avant codage ;
15. création du plan et de la validation de release.

Documents attendus :

```text
docs/plans/034-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE_PLAN.md
docs/validation/030-V0_3_13_MULTI_SOURCE_LIVE_CONVERGENCE.md
```

Critère de sortie : chaque source retenue et la convergence doivent avoir un contrat d'entrée/sortie, des bornes, une stratégie de preuve et un propriétaire de retry/reconnect clairement identifiés avant `pre.002`.

## 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 WS/Helius/HTTP courant, matrice de matériau/hydration, architecture multi-source, threat model, smokes, graphes, plan/validation et décision de maintien/rescission.

### `pre.002` — contrat runtime resources multi-source

Généraliser la composition caller-owned vers plusieurs sources bornées, avec identité interne/source lifecycle minimale, sans brancher encore toutes les voies live.

### `pre.003` — WS standard `logsSubscribe` + hydration

Brancher la discovery signature/logs via la façade Transport existante et fermer `logs -> getTransaction observed -> Common RAW` sans recopier l'actor WS.

### `pre.004` — WS standard `blockSubscribe`

Brancher les blocs full/base64 et utiliser RAW-direct uniquement pour les versions réellement qualifiées ; hydration/fault explicite ailleurs.

### `pre.005` — Helius `transactionSubscribe`

Réutiliser la surface Transport Helius existante, appliquer l'hydration nécessaire et les profils Config réellement justifiés sans SDK ni secret dans le Worker.

### `pre.006` — HTTP live block polling

Suivre le réseau depuis une borne de run explicite, récupérer les blocs observed et projeter leurs transactions vers le pipeline central avec cadence/bornes/stop déterministes.

### `pre.007` — supervision/source inventory multi-source

Faire coexister plusieurs sources dans le supervisor, avec ownership clair des tasks, stop/fault et source health sans modifier la sémantique Worker globale arbitrairement.

### `pre.008` — convergence et observations multiples

Fermer la déduplication/coalescence cross-source et la conservation de provenances/observations distinctes pour une même identité canonique.

### `pre.009` — conflits, backpressure et fairness

Durcir disagreement cross-source, content conflict, saturation globale/par source, fairness minimale et absence de fanout d'hydration non borné.

### `pre.010` — snapshots/health multi-source

Projeter uniquement les dimensions source-neutral réellement utiles : activité, source failures, backpressure et état agrégé sans exposer provider material.

### `pre.011` — races/shutdown hardening

Stop/fault pendant connect/resubscribe/hydration/polling/persistence, sources lentes, tasks orphelines, counters et ordre terminal.

### `pre.012` — completeness/security cross-layer

Canaris Transport -> Worker -> Common RAW -> Store, inventaires API/dépendances, redaction, Legacy/V0/V1 et non-régression Yellowstone.

### `pre.013` — gate technique/live

Workspace complet, Clippy strict, suites ciblées, graphes/duplicates et smokes réellement accessibles. Aucun nouveau scope.

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

README/USAGE, plan, validation et architectures/références réellement affectées. Pas de CHANGELOG/ROADMAP/prompt suivant.

### `pre.015` — préparation publication

Prompt `0.3.14`, CHANGELOG, ROADMAP et fichiers mécaniques uniquement.

### `rel.001`

Publication stable mécanique après gate validé.

Le forecast peut être allongé par des fixes/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.13-pre.NNN
Cargo               : 0.3.13-pre.N
fix                  : 0.3.13-pre.N.fix.M
delta                : deltas/0.3.13/pre.NNN.md ou pre.NNN-fix.NNN.md
commit               : v0.3.13-pre.NNN[-fix.NNN]
tag prerelease       : aucun
tag stable final     : v0.3.13 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 Helius sont modifiés :

```bash
cargo test -p ksp-config-lib
```

Graphes à maintenir/auditer :

```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 configurés :

```text
Solana HTTP Devnet
Solana WS Devnet
Helius transactionSubscribe si credential/tier disponible
provider WS/blockSubscribe réellement accessible
HTTP polling live sur réseau de test approprié
```

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.13`

La release peut se fermer lorsque :

```text
base Yellowstone 0.3.12 non régressée
runtime resources supporte les sources retenues de manière bornée
logsSubscribe + hydration productif
blockSubscribe productif sur les versions réellement qualifiées
Helius transactionSubscribe productif si retenu/accessible par pre.001
HTTP live polling productif et run-local
sources simultanées convergent vers la même admission/persistence
observations multiples conservées sans dupliquer l'identité RawTransaction
content conflict reste explicite
coalescence/hydration fanout/backpressure bornés
aucun second actor/client Transport dans le Worker
aucun Worker -> Config/Job/backend physique
retry/reconnect restent possédés par la couche appropriée
shutdown/fault multi-source sans tâches orphelines
diagnostics redacted
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.14 produit dans la dernière prerelease
```

## 15. Release suivante envisagée

`0.3.14` doit reprendre uniquement après publication stable de `0.3.13` et fermer le **gap repair/hardening multi-source** :

```text
replay natif lorsqu'il est réellement adressable
source redondante comme preuve/couverture de gap
scan HTTP blocs pour réparation
hydration des références manquantes
unresolved gaps explicitement observables
politiques degraded/unhealthy/faulted
shutdown pendant repair
smokes provider accessibles
EARLY uniquement si réellement prouvé et encore justifié
```

`0.3.14` ne doit toujours pas transformer le Worker en moteur de campagne historique paramétrée ; le Backfill reste indépendant.

## 16. Instruction d'ouverture

Au début de la prochaine session :

1. vérifier que la base correspond exactement au tag stable `v0.3.12` et que `deltas/0.3.12/rel.001.md` est présent ;
2. lire les règles, le handoff `0.3.12`, l'architecture RAW acquisition et les sources Worker/Transport/Common/Store/Config avant toute modification ;
3. réauditer les surfaces Solana WS, Helius et HTTP actuelles ainsi que les tiers/versions réellement concernés ;
4. produire `0.3.13-pre.001` avec matrice source/material/hydration, architecture multi-source, threat model, sizing, plan `034` et validation `030` ;
5. **ne pas généraliser runtime resources, ne pas brancher `logsSubscribe`/`blockSubscribe`/Helius, ne pas ajouter de polling et ne pas modifier Config avant fermeture de ce gate** ;
6. rescinder `0.3.13` immédiatement si le périmètre réel n'est pas clôturable dans une seule session.