0.3.16-pre.001

docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md

@@ -0,0 +1,388 @@
+<!-- file: docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md -->
+<!-- version: 1 -->
+
+# Validation `0.3.16` — résilience RAW et gestion des conflits
+
+## 1. Objet
+
+Ce document suit la validation de `0.3.16` depuis le gate `pre.001` jusqu'à la fermeture stable.
+
+La première tranche ne prétend pas valider une implémentation qui n'existe pas encore. Elle valide le point de départ, les contrats acquis, les décisions d'architecture et la liste des preuves à construire.
+
+## 2. Base stable
+
+Base requise :
+
+```text
+v0.3.15
+commit 7328be6997399c513306f2f4c8cdf00bd8b22367
+```
+
+Le delta stable `0.3.15-rel.001` documente :
+
+```text
+cargo fmt --all -- --check : PASS
+General Rust rule audit : clean
+Rust export completeness audit : 0 candidate(s)
+KSP workspace Rust rule audit : clean
+Markdown table audit : clean (318 table(s), 232 file(s))
+cargo check --workspace : PASS
+```
+
+Il documente également le gate technique/live de `pre.016`, le live Mainnet Yellowstone + HTTP Block Polling d'environ dix-neuf minutes et la fermeture `Stopped/Healthy` des deux routes.
+
+Ces résultats appartiennent à la fermeture `0.3.15` ; ils ne sont pas revendiqués comme réexécutés par `0.3.16-pre.001`.
+
+## 3. Limitation de vérification de l'archive source dans l'environnement d'assemblage
+
+L'arbre canonique du tag et le commit stable ont été vérifiés via le dépôt public.
+
+L'archive binaire source `v0.3.15.zip` n'a pas pu être matérialisée dans l'environnement d'assemblage de `pre.001`. Aucun SHA/CRC ou byte-compare local de cette archive n'est donc déclaré PASS ici.
+
+Cette limitation ne doit pas être masquée par les gates historiques du delta stable.
+
+Après application du delta sur le checkout utilisateur taggé `v0.3.15`, les scripts et commandes du dépôt restent l'autorité de validation locale.
+
+## 4. Vérification des règles
+
+Le gate `pre.001` a réaudité les familles de règles requises par le prompt :
+
+```text
+RULES.md
+RULES_GENERAL.md
+RULES_KSP.md
+RULES_RUST.md
+RULES_DEPENDENCIES.md
+RULES_DOCUMENTATION.md
+FILE_CONTRACTS.md
+VERSION_WORKFLOW.md
+PROMPT_STRUCTURE.md
+```
+
+Décisions directement dérivées de ces règles :
+
+- première livraison `0.3.16-pre.001` -> Cargo `0.3.16-pre.1` ;
+- aucun Rust ni SQL lourd dans le gate d'ouverture ;
+- delta minimal ;
+- migrations V000/V001/V002 immuables ;
+- Store-lib façade unique ;
+- aucune dépendance Worker <-> Job Backfill ;
+- aucune queue non bornée ;
+- aucun PASS inventé ;
+- pas de `npm run build` comme gate Desk.
+
+## 5. Inventaire de caractérisation `0.3.15`
+
+### 5.1 Store RAW
+
+Caractérisé :
+
+```text
+identity = network + signature au contrat
+backend PostgreSQL = une base liée à un network
+canonical unique actuel
+atomic canonical + observation
+additional observation
+content_conflict terminal hors cas narrow logs
+retention Full / Archived / Purged / ForceRehydrate
+```
+
+### 5.2 Outcomes actuels
+
+Caractérisés :
+
+```text
+Inserted
+AlreadyPresent
+Rehydrated
+SkippedPurged
+
+Observation:
+Inserted
+AlreadyPresent
+NotRecorded
+```
+
+### 5.3 PostgreSQL
+
+Caractérisé :
+
+```text
+V000/V001/V002
+migration registry + checksum
+transaction d'écriture
+collision identité
+SELECT ... FOR UPDATE
+comparaison canonique
+observation transactionnelle
+retention sous verrou
+```
+
+### 5.4 Worker
+
+Caractérisé :
+
+```text
+convergence run-local existante
+Store content_conflict -> faute persistence
+faute persistence -> arrêt de source / route terminale
+pas de Store retry policy dédiée comparable au reconnect Transport
+```
+
+### 5.5 Transport
+
+Caractérisé :
+
+```text
+HTTP request retry déjà Transport-owned
+WebSocket reconnect borné avec backoff
+Yellowstone reconnect borné avec backoff
+Config projection déjà existante
+```
+
+### 5.6 Store Desk
+
+Caractérisé :
+
+```text
+inspection via ksp-store-lib
+pas de SQL direct
+pas encore de variants/conflicts/resolution actions
+```
+
+## 6. Preuves externes réauditées
+
+### 6.1 Log truncation
+
+Le collecteur SVM courant expose :
+
+```text
+LOG_MESSAGES_BYTES_LIMIT = 10 * 1000
+```
+
+et ajoute exactement :
+
+```text
+Log truncated
+```
+
+une seule fois lorsque la limite est atteinte/dépassée, puis cesse d'enregistrer les lignes suivantes.
+
+Canari requis pour `pre.006` :
+
+```text
+truncated exact prefix + marker vs full continuation
+  -> Less/More selon direction
+
+different prefix before marker
+  -> Conflict
+
+shorter list without marker
+  -> Conflict/Incomparable
+```
+
+### 6.2 Autres champs RPC
+
+La documentation Solana actuelle montre des différences de sérialisation/optionnalité pour :
+
+```text
+innerInstructions
+loadedAddresses
+returnData
+computeUnitsConsumed
+costUnits
+rewards
+preTokenBalances
+postTokenBalances
+```
+
+Canari de politique : aucune de ces différences ne produit `CompatibleLessComplete` ou `CompatibleMoreComplete` sans nouvelle preuve normative explicite.
+
+### 6.3 PostgreSQL
+
+Les mécanismes retenus sont compatibles avec la stratégie :
+
+- `SELECT ... FOR UPDATE` sérialise les writers/lockers concurrents d'une même ligne jusqu'à fin de transaction ;
+- `INSERT ... ON CONFLICT` possède une sémantique atomique pour les conflits arbitrés ;
+- certaines fautes d'isolation/serialization exigent le retry de la transaction complète.
+
+Ces propriétés doivent être traduites en tests KSP et non seulement citées dans la documentation.
+
+## 7. Décisions fermées par `pre.001`
+
+### 7.1 Modèle physique
+
+Décision : ledger V003 de variantes à `variant_id` surrogate + sélecteur canonique sidecar + projection V001 compatible.
+
+### 7.2 Hash
+
+Décision : `content_hash` est un préfiltre/intégrité, jamais la preuve unique d'égalité lorsque les bytes sont disponibles.
+
+### 7.3 Observations
+
+Décision : toute nouvelle observation V003 pointe vers la variante réellement reçue.
+
+Les observations legacy impossibles à reconstruire sont qualifiées explicitement comme telles.
+
+### 7.4 Rétention
+
+Décision : toute variante requise pour conflit ouvert, canonique courant, restauration ou parent synthétique peut être archivée mais reste protégée contre une purge irréversible tant que l'invariant de rollback dépend de ses bytes.
+
+### 7.5 Conflict case
+
+Décision : état principal `Open | Resolved`, réouverture possible, journal append-only des transitions/résolutions.
+
+### 7.6 Qualité
+
+Décision : relation interne :
+
+```text
+Exact
+CompatibleLessComplete
+CompatibleMoreComplete
+Conflict
+Incomparable
+```
+
+`Incomparable` est persisté prudemment comme réconciliation ouverte.
+
+### 7.7 Store retry
+
+Décision :
+
+```text
+Store backend -> classifie Transient/Terminal
+Worker -> orchestre retry/backpressure/health
+```
+
+### 7.8 Transport reconnect
+
+Décision : reste dans `ksp-onchain-transport-lib` ; extension du mécanisme existant, sans fusion conceptuelle avec Store retry ni coverage.
+
+### 7.9 Store Desk
+
+Décision : conflits/historique/actions via `ksp-store-lib` uniquement, bridge Tauri typé, frontend Vite/TypeScript, actions protégées par revision attendue.
+
+## 8. Matrice de preuves à construire
+
+### 8.1 API
+
+À prouver :
+
+- roundtrip/égalité des DTO variant/conflict/history ;
+- reason codes stables ;
+- outcomes distincts ;
+- classification Store transient/terminal sans type PostgreSQL exposé.
+
+### 8.2 Migration V003
+
+À prouver :
+
+- checksums V000/V001/V002 inchangés ;
+- V003 idempotente dans le registry ;
+- base vide ;
+- base existante Full ;
+- base existante Archived ;
+- base existante Purged ;
+- observation legacy non faussement attribuée ;
+- rollback de migration selon contrat KSP si applicable.
+
+### 8.3 Variants/convergence
+
+À prouver :
+
+- exact concurrent -> une variante logique ;
+- less complete logs -> canonique inchangé ;
+- more complete logs -> promotion atomique ;
+- conflict -> canonique inchangé + variante durable + case Open ;
+- incomparable -> fail-closed durable ;
+- hash identique + payload différent -> jamais fusionné par hash seul.
+
+### 8.4 Promotions
+
+À prouver :
+
+- selector et projection V001 cohérents après commit ;
+- ancien canonique conservé ;
+- restore local sans Internet ;
+- stale revision rejetée ;
+- crash/rollback ne laisse pas selector/projection divergents.
+
+### 8.5 Rétention
+
+À prouver :
+
+- archive d'une variante rollbackable conserve bytes exacts ;
+- purge refusée lorsqu'une variante est épinglée ;
+- ForceRehydrate exact ;
+- ForceRehydrate payload différent -> nouvelle variante ;
+- legacy Purged ne prétend pas disposer d'une égalité byte-exact perdue.
+
+### 8.6 Worker
+
+À prouver :
+
+- conflit durable -> route Running, health Degraded ;
+- autre identité continue ;
+- Store transient -> retry sans success prématuré ;
+- queue bornée -> backpressure ;
+- policy exhausted -> terminal explicite ;
+- Stop pendant backoff -> cancellation/drain propre.
+
+### 8.7 Transport
+
+À prouver :
+
+- backoff initial/max/multiplier ;
+- max attempts ;
+- reset stable ;
+- jitter borné ;
+- reconnexion != coverage ;
+- comportement HTTP existant non régressé.
+
+### 8.8 Store Desk
+
+À prouver :
+
+- pagination bornée ;
+- aucune dépendance backend direct ;
+- promote/keep/restore/reopen typés ;
+- stale action visible et recharge ;
+- aucune donnée sensible dans tracing frontend/backend ;
+- build via Tauri/Vite seulement.
+
+## 9. Gates de `pre.001` exécutables après application
+
+Comme cette archive delta ne contient pas le checkout complet, les commandes KSP suivantes ne sont pas revendiquées exécutées dans l'environnement d'assemblage :
+
+```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
+```
+
+Elles doivent être exécutées sur le dépôt utilisateur après application de `pre.001`.
+
+Aucun `npm run build` n'est demandé.
+
+## 10. Gate de sortie `pre.001`
+
+État documentaire :
+
+```text
+modèle conceptuel                  CLOSED
+frontières de crates               CLOSED avec vérification Cargo à chaque tranche
+migration strategy                 CLOSED
+logMessages quality semantics      CLOSED
+other field policy                 CLOSED / fail-closed
+Store retry ownership              CLOSED
+Transport reconnect ownership      CLOSED
+Store Desk scope                   CLOSED
+races/retention risks              IDENTIFIED
+prerelease sizing                  RECALIBRATED
+out-of-scope                       CLOSED
+```
+
+L'implémentation lourde peut commencer en `pre.002` uniquement après application locale et gate propre du delta `pre.001`.