khadhroony-solana-project/prompts/036-V0_3_17_START_PROMPT.md

<!-- file: prompts/036-V0_3_17_START_PROMPT.md -->
<!-- version: 1 -->

# Prompt de démarrage `0.3.17` — résilience opérationnelle et cycle de vie des variantes RAW

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

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

```text
v0.3.16
```

Ne pas démarrer depuis `0.3.16-pre.*`, depuis une archive intermédiaire ou depuis un état de travail non taggé.

La première livraison attendue est :

```text
0.3.17-pre.001
```

`pre.001` est obligatoirement un gate de **lecture + audit Store API/Store/PostgreSQL/Worker/Transport/Config + audit du cycle de vie durable des variantes/conflits + audit des erreurs transient/terminal + brainstorming + sizing + planification**.

Il est interdit de commencer directement par une UI Store Desk, un moteur de retry générique, une migration opportuniste ou une boucle de reconnexion parallèle avant fermeture de ce gate.

## 2. Mission et résultat attendu

`0.3.16` a livré les fondations multi-variantes : comparaison fail-closed, sélecteur canonique, promotion strictement prouvée, conservation des variantes et quarantaine durable minimale sans arrêt du Worker.

`0.3.17` doit transformer cette fondation en mécanisme opérable et résilient côté backend/runtime, sans ouvrir encore l'UI Store Desk.

Le résultat cible est :

```text
plusieurs représentations RAW durables
    -> inspection backend-neutral
    -> conflict case complet et revisionné
    -> participants/historique durable
    -> résolution explicite et concurrent-safe
    -> restore/reopen possibles selon contrat
    -> rétention/pins empêchant la perte d'une variante encore nécessaire

Store temporairement indisponible
    -> classification Transient / Terminal
    -> retry borné avec backpressure explicite
    -> aucun drop silencieux
    -> health/activity cohérentes
    -> cancellation/drain pendant backoff

Transport live temporairement indisponible
    -> mécanisme de reconnexion propriétaire réutilisé
    -> configuration bornée
    -> aucune confusion entre reconnexion, replay delivery et preuve de coverage
```

La release doit fournir les contrats nécessaires à `0.3.18`, où `ksp-app-store-desk` exposera ensuite l'inspection et les actions opérateur.

## 3. Principes directeurs acquis

Les principes suivants sont déjà décidés et ne doivent pas être redébattus sans preuve nouvelle :

```text
une divergence de données != une panne d'acquisition
Store est l'autorité de convergence durable
une provenance/provider n'est jamais une priorité canonique en soi
content_hash seul n'est jamais une preuve d'égalité lorsque les bytes sont disponibles
la dominance reste fail-closed
seule une complétude explicitement prouvée autorise une promotion automatique
un conflit non résolu conserve toutes les variantes nécessaires
reconnexion != coverage
retry != duplication silencieuse
```

Le Worker ne doit pas réintroduire un arbitre run-local plus fort que le Store.

## 4. Sources de vérité internes obligatoires — ordre de lecture

### 4.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 présent prompt complète ces règles ; il ne les remplace pas.

Rappels bloquants :

```text
Rust 2024
unsafe interdit
unwrap / expect / panic interdits selon les règles KSP
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 via crate root
accès partagés via crate::Item, y compris intra-crate
unit tests sous unit_tests/
integration tests sous tests/
```

### 4.2 Handoff stable `0.3.16`

Lire intégralement :

```text
prompts/035-V0_3_16_START_PROMPT.md
docs/plans/037-V0_3_16_RAW_RESILIENCE_CONFLICT_HANDOFF.md
docs/plans/038-V0_3_16_RAW_RESILIENCE_CONFLICT_PLAN.md
docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md

deltas/0.3.16/pre.001.md
...
deltas/0.3.16/pre.010.md
deltas/0.3.16/rel.001.md
```

Les `pre.*-fix.*` réellement présents doivent également être lus lorsqu'ils corrigent une tranche citée.

Lorsque `rel.001.md` n'est pas encore présent dans l'archive fournie à l'ouverture de la session, **ne pas l'inventer** : vérifier d'abord que la base est bien le tag stable `v0.3.16` et utiliser le commit/tag comme autorité.

### 4.3 Store API et façade

Lire et auditer réellement :

```text
crates/ksp-store-api/README.md
crates/ksp-store-api/USAGE.md
crates/ksp-store-api/src/
crates/ksp-store-api/tests/

crates/ksp-store-lib/README.md
crates/ksp-store-lib/USAGE.md
crates/ksp-store-lib/src/
crates/ksp-store-lib/tests/
```

Auditer en particulier :

```text
RawTransactionVariant*
RawTransactionVariantComparison
RawTransactionVariantWriteOutcome
RawAcquisitionWriteOutcome
capabilities RawTransaction existantes
surface d'inspection actuelle
codes d'erreur Store et backend-neutralité
object safety et stabilité des traits publics
rétention RawTransaction existante
```

`0.3.17-pre.001` doit décider les DTOs/capabilities backend-neutral nécessaires pour :

```text
lister/inspecter variantes
lister/inspecter conflict cases
lire l'historique de résolution
résoudre/promouvoir/conserver/restaurer/réouvrir avec revision attendue
classifier les erreurs Store Transient / Terminal sans exposer le backend physique
```

Aucune API publique ne doit exposer `tokio-postgres`, SQL, row handles ou détails provider.

### 4.4 Backend PostgreSQL et migration V003

Lire :

```text
crates/ksp-store-postgres-lib/README.md
crates/ksp-store-postgres-lib/USAGE.md
crates/ksp-store-postgres-lib/src/
crates/ksp-store-postgres-lib/tests/
crates/ksp-store-postgres-lib/unit_tests/
crates/ksp-store-postgres-lib/resources/
```

État acquis à préserver :

```text
V000/V001/V002 figés
V003 additive
ksp_raw_transaction_variants
ksp_raw_transaction_canonical_selectors
ksp_raw_transaction_observation_variants
ksp_raw_transaction_conflicts
```

Le sélecteur canonique et la projection V001 doivent rester atomiquement cohérents.

Toute extension physique de `0.3.17` doit être additive, migrationnée et justifiée par un contrat métier réel. Ne pas modifier rétroactivement les ressources/checksums stables.

Auditer avant conception :

```text
FOR UPDATE / ordre des locks
revision compare-and-set
participants d'un conflict case
historique append-only
reopen après résolution
races ingestion <-> résolution
races résolution <-> rétention
rollback transactionnel
idempotence des actions opérateur
```

### 4.5 Common RAW et règles de comparaison

Lire :

```text
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/
```

Le comparateur `0.3.16` reste l'autorité de classification automatique. Ne pas élargir la dominance pour faciliter l'UI ou réduire artificiellement le nombre de conflits.

État acquis :

```text
Exact
CompatibleLessComplete
CompatibleMoreComplete
Conflict
Incomparable
```

La seule dominance actuellement prouvée concerne les formes strictes de troncature `logMessages` documentées. Les autres différences restent fail-closed tant qu'une preuve spécifique n'existe pas.

### 4.6 Worker live

Lire :

```text
crates/ksp-worker-api/
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/
```

État acquis :

```text
chaque acquisition atteint le Store
convergence run-local = sérialisation seulement
QuarantinedConflict = succès durable non terminal
Worker reste Running
health devient Degraded
legacy ERROR_CODE_RAW_CONFLICT reste terminal uniquement comme compatibilité backend ancien
```

`0.3.17` doit ajouter le comportement Store transient sans perdre cet invariant.

La politique de retry doit expliciter :

```text
quels codes/classes sont Transient
quels codes/classes sont Terminal
borne de tentatives ou budget temporel
backoff borné
jitter éventuel et ownership
backpressure amont
état Blocked/Degraded/Unhealthy attendu
cancellation pendant sleep/backoff
shutdown/drain avec tentative en vol
absence de double persistence après résultat durable
```

### 4.7 Transport et Config

Lire :

```text
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/
crates/ksp-onchain-transport-lib/tests/

crates/ksp-config-lib/README.md
crates/ksp-config-lib/USAGE.md
crates/ksp-config-lib/src/
crates/ksp-config-lib/tests/
```

Réutiliser les mécanismes propriétaires actuels HTTP/WebSocket/Yellowstone. Ne pas créer une seconde pile réseau dans le Worker.

La reconnexion configurable doit conserver la séparation :

```text
reconnect attempt
session resume / from_slot / ReplayInfo lorsque disponible
replay delivery
coverage proof
```

Aucun de ces éléments ne vaut automatiquement un autre.

### 4.8 Job Backfill existant

Lire au minimum :

```text
crates/ksp-job-backfill-lib/README.md
crates/ksp-job-backfill-lib/USAGE.md
crates/ksp-job-backfill-lib/src/persistence.rs
crates/ksp-job-backfill-lib/unit_tests/persistence.rs
```

Le Job Backfill reste un producteur indépendant et doit continuer de fonctionner avec les évolutions Store. `0.3.17` n'est pas la release du Backfill multi-route/multi-stratégie.

### 4.9 Architecture et références durables

Lire :

```text
docs/architecture/004-COMPONENT_INVENTORY.md
docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md
docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md
```

Ces documents décrivent l'état réconcilié à la fermeture de `0.3.16` et doivent servir de baseline, pas les anciens objectifs devenus obsolètes du prompt `035`.

## 5. Sources externes normatives à réauditer en `pre.001`

Réauditer uniquement les sources officielles ou upstream réellement nécessaires :

```text
PostgreSQL : transactions, row locking, deadlocks, serialization failures et SQLSTATE
Tokio PostgreSQL : erreurs de connexion/IO/DB et possibilités de classification sûres
Solana JSON-RPC/WebSocket : comportement de session/subscription/reconnect applicable
Yellowstone gRPC upstream : lifecycle de stream, fermeture, reprise/from_slot/ReplayInfo applicable
Tokio/Tonic/Tungstenite utilisés par les crates actuelles : cancellation/reconnect lorsque pertinent
```

La réaudition doit distinguer :

```text
fait documenté upstream
comportement observé par KSP
politique KSP choisie
```

Ne jamais transformer un message d'erreur provider arbitraire en contrat public KSP.

## 6. État validé de `0.3.16` à préserver

À l'ouverture de `0.3.17`, considérer comme acquis uniquement ce qui est présent dans le tag `v0.3.16` et confirmé par ses deltas/validation.

La baseline attendue comprend :

```text
Store API comparator backend-neutral
V003 additive et historique V000/V001/V002 intact
variants durables
canonical selector revisionné
observation -> variant mapping
conflict case minimal durable
promotion CompatibleMoreComplete atomique
ancien canonique conservé comme variante
Conflict/Incomparable quarantinés sans mutation canonique
Worker Running/Degraded après QuarantinedConflict
Backfill projection Conflict compatible
PostgreSQL live proof exécutée sur PostgreSQL 17
```

Le gate final de `0.3.16` doit être lu dans `docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md` et dans les deltas de fermeture ; ne pas inventer un résultat non enregistré.

## 7. Cycle de vie complet des conflict cases

Le modèle minimal `0.3.16` ne suffit pas à une résolution opérateur complète.

`pre.001` doit cadrer précisément :

```text
identité stable du conflict case
participants/variantes concernées
status Open / Resolved et éventuels états supplémentaires réellement nécessaires
reason/relation conservées
revision monotone
resolved canonical variant
actor/reason opérateur si un contrat KSP sûr le justifie
journal append-only de transitions
reopen quand une nouvelle divergence survient
idempotence d'une résolution répétée
stale revision explicite
```

Une résolution ne doit jamais détruire immédiatement la variante perdante si elle reste nécessaire à l'historique, au rollback ou à un conflict case ouvert.

## 8. Actions et concurrence

Les actions opérateur futures de `0.3.18` doivent être rendues sûres par les contrats backend de `0.3.17`.

Auditer et définir au minimum :

```text
promote candidate
keep current canonical
restore previous variant
resolve conflict
reopen conflict
```

Chaque action mutable doit avoir une sémantique de revision attendue ou équivalent compare-and-set. Une action stale doit échouer explicitement sans écraser une décision concurrente.

Les races à couvrir incluent :

```text
ingestion -> nouvelle variante pendant résolution
promotion automatique -> résolution manuelle concurrente
résolution A -> résolution B concurrente
réouverture -> résolution précédente
rétention/purge -> variante encore référencée
force rehydrate -> identité existante avec bytes exacts/différents
```

## 9. Rétention, pins et rollback

La rétention doit être définie avant tout purge de variante.

Principe :

```text
une variante nécessaire à un selector, conflict case ouvert, historique de résolution ou rollback autorisé ne peut pas disparaître silencieusement
```

`pre.001` doit décider :

```text
quels objets pin une variante
quand un pin peut être relâché
archive vs purge
interaction avec RawRetentionState V001
interaction avec ForceRehydrate
restore depuis variante locale conservée
comportement si une ancienne variante est déjà physiquement absente
```

Le réseau n'est pas un mécanisme normal de rollback d'une variante précédemment connue.

## 10. Classification Store `Transient / Terminal`

La classification doit être backend-neutral à la frontière publique tout en restant suffisamment précise pour le runtime.

Ne pas classifier par texte libre d'erreur.

`pre.001` doit produire une matrice au moins pour :

```text
connexion indisponible / reset
pool temporairement indisponible
timeout/cancellation locale
deadlock/serialization retryable si applicable
constraint/data-invalid
migration/schema mismatch
network mismatch KSP
stale revision
retention conflict
secret/config invalid
```

La classe publique doit être stable et sûre ; le backend conserve les détails physiques privés.

## 11. Retry Store, backpressure et état `Blocked`

Le retry appartient au Worker/runtime consumer, pas au backend PostgreSQL sous forme de boucle cachée illimitée.

Le Store backend peut classifier et retourner ; le Worker décide une politique bornée selon les contrats KSP.

Le design doit éviter :

```text
queue mémoire non bornée
retry storm
sleep non cancellable
perte silencieuse après exhaustion
health Healthy pendant une impossibilité persistante de commit
double écriture après succès ambigu sans idempotence
```

La relation avec les limites actuelles `in_flight`/admission doit être explicitement testée.

## 12. Reconnexion Transport configurable

`0.3.17` étend les mécanismes existants ; il ne crée pas une abstraction universelle inventée au-dessus de toutes les routes.

La configuration doit être bornée et cohérente avec les contrats Config existants :

```text
attempt/backoff limits
connect/session deadlines
stop preemption
source supervision
replay/from_slot lorsque réellement supporté
```

Une reconnexion réussie ne ferme aucun gap à elle seule. Les contrats `0.3.14` de coverage/gap repair restent autoritaires.

## 13. Frontières de crates et hors UI

Frontières cibles :

```text
ksp-store-api
    DTOs/capabilities backend-neutral

ksp-store-postgres-lib
    SQL, locks, transactions, migrations, classification physique

ksp-store-lib
    façade et dispatch backend-neutral

ksp-worker-raw-transaction-ingest-lib
    politique retry/backpressure/health/cancellation

ksp-onchain-transport-lib
    sessions/reconnect/replay transport-owned

ksp-config-lib
    configuration bornée des mécanismes existants
```

`ksp-app-store-desk` n'est pas à développer dans `0.3.17`. Seuls les contrats nécessaires à sa future utilisation doivent être stabilisés.

## 14. Sécurité et redaction

Ne jamais exposer dans erreurs/logs/snapshots publics :

```text
URI PostgreSQL
password/token/API key
endpoint complet lorsque sa publication n'est pas nécessaire
payload RAW
signature brute si les règles de surface l'interdisent
server error arbitraire
SQL complet
row/backend handle
```

Les diagnostics de conflits existants restent bornés et structurels.

Toute nouvelle action de résolution doit journaliser seulement les identifiants/codes sûrs nécessaires à l'audit.

## 15. Première mission `pre.001` — audit, brainstorming et sizing

Avant toute implémentation lourde :

1. vérifier que la base est exactement `v0.3.16` ;
2. lire toutes les sources internes de la section 4 ;
3. réauditer les sources externes pertinentes de la section 5 ;
4. inventorier les contrats publics actuels Store/Worker/Transport/Config ;
5. produire le modèle conceptuel complet conflict case / participants / history / resolution / reopen ;
6. produire la stratégie de revision/CAS et la matrice des races ;
7. produire la politique de rétention/pins/rollback/ForceRehydrate ;
8. produire la classification `Transient / Terminal` et son ownership ;
9. produire la politique Worker de retry/backpressure/Blocked/cancellation ;
10. produire la politique Transport reconnect/config sans confondre coverage ;
11. auditer la compatibilité du Job Backfill existant ;
12. dimensionner les migrations/tests/live proofs ;
13. créer ou réviser le plan `0.3.17` avec prereleases bornées ;
14. publier seulement ensuite `0.3.17-pre.001`.

Critères de sortie `pre.001` :

```text
contrats Store API proposés et bornés
modèle conflict lifecycle validé
revision/race semantics validées
rétention/pins validés
classification Transient/Terminal validée
retry ownership et bornes validés
reconnect ownership et bornes validés
compatibilité Backfill explicitée
migration strategy validée
preuves live nécessaires identifiées
prévision souple des prereleases publiée
hors-périmètre explicite
```

## 16. Prévision souple initiale des prereleases

Cette trajectoire provient du plan réconcilié `0.3.16`. Elle doit être réauditée en `pre.001` et peut être subdivisée si le sizing l'exige.

```text
pre.001  audit + contrats Store API inspection/résolution + classification Transient/Terminal + plan
pre.002  conflict cases complets : participants, résolution, reopen, historique append-only, races
pre.003  rétention des variantes : archive, pins, purge guards, rollback local, ForceRehydrate
pre.004  ksp-store-lib : inspection/historique/actions backend-neutral + compatibilité Backfill
pre.005  Worker : Store retry/backpressure/Blocked, exhaustion, cancellation et drain pendant backoff
pre.006  Transport/Config : reconnect WebSocket/Yellowstone configurable sur mécanismes existants
pre.007  hardening cross-layer + preuves live ciblées Store outage/recovery, retry, reconnect, concurrence
pre.008  réconciliation documentaire finale
pre.009  préparation de publication : CHANGELOG + ROADMAP + prompt 0.3.18
rel.001  publication stable mécanique
```

Ne jamais fusionner artificiellement les couloirs de fermeture. Les règles `VER-LIFECYCLE-*` restent autoritaires si le nombre de tranches évolue.

## 17. Hors périmètre de `0.3.17`

Ne pas inclure :

```text
frontend/backend Tauri Store Desk de résolution -> 0.3.18
backfill multi-route/multi-stratégie -> 0.3.19
adaptation Backfill Desk -> 0.3.20
RAW -> STRUCTURAL
persistence STRUCTURAL
DECODED / DOMAIN
majority voting provider
priorité provider
fusion heuristique de JSON arbitraire
retry illimité caché dans le backend Store
nouvelle pile réseau Worker parallèle à Transport
nouvelle dépendance Worker <-> Backfill
```

## 18. Versionnement, deltas, validation et instruction d'ouverture

Respecter strictement `docs/rules/VERSION_WORKFLOW.md`.

Les deltas de `0.3.17` utilisent :

```text
ksp-general-0.3.17-pre.NNN.zip
ksp-general-0.3.17-pre.NNN-fix.NNN.zip
```

Après toute modification Rust :

```bash
cargo fmt --all
cargo fmt --all -- --check
python3 scripts/audit_rust_workspace_rules.py
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
```

Pour tout Markdown touché :

```bash
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas
```

Les tests ciblés sont préférés pendant le développement ; les gates complets et live proofs sont réservés aux tranches prévues et ne sont déclarés PASS que lorsqu'ils ont réellement été exécutés.

Les tests PostgreSQL live qui lisent une URI dédiée sur `stdin` doivent continuer à ne jamais l'échoer ni la conserver dans les logs/deltas.

Pour les applications Desk, ne pas utiliser `npm run build` comme gate manuel. `0.3.17` ne développe normalement pas la Store Desk ; si un smoke Tauri devenait nécessaire pour une compatibilité mécanique, utiliser le workflow Tauri/Vite KSP prévu par les règles.

### Instruction d'ouverture de la prochaine session

Commencer par :

```text
1. vérifier que la base est exactement le tag stable v0.3.16 ;
2. lire toutes les sources internes de la section 4 dans l'ordre ;
3. réauditer les sources externes pertinentes de la section 5 ;
4. exécuter la mission pre.001 de la section 15 ;
5. produire le plan/sizing avant toute migration ou développement lourd.
```

Ne pas commencer par l'UI Store Desk, par une boucle de retry ou par une migration avant d'avoir fermé le gate `pre.001`.

La trajectoire suivante est :

```text
0.3.17  résilience opérationnelle + cycle de vie des variantes
0.3.18  Store Desk inspection/résolution des variantes et conflits
0.3.19  Backfill multi-route/multi-stratégie
0.3.20  Backfill Desk correspondant
```