khadhroony-solana-project/docs/validation/033-V0_3_16_RAW_RESILIENCE_CONFLICT.md

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 :

v0.3.15
commit 7328be6997399c513306f2f4c8cdf00bd8b22367

Le delta stable 0.3.15-rel.001 documente :

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 :

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é :

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 :

Inserted
AlreadyPresent
Rehydrated
SkippedPurged

Observation:
Inserted
AlreadyPresent
NotRecorded

5.3 PostgreSQL

Caractérisé :

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é :

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é :

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é :

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 :

LOG_MESSAGES_BYTES_LIMIT = 10 * 1000

et ajoute exactement :

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 :

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 :

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 :

Exact
CompatibleLessComplete
CompatibleMoreComplete
Conflict
Incomparable

Incomparable est persisté prudemment comme réconciliation ouverte.

7.7 Store retry

Décision :

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 :

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 :

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.