0.3.15-pre.012-fix.004

docs/validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md

@@ -1,5 +1,5 @@
 <!-- file: docs/validation/032-V0_3_15_RAW_TRANSACTION_INGEST_DESK.md -->
-<!-- version: 25 -->
+<!-- version: 26 -->
 
 # Validation v0.3.15 — Raw Transaction Ingest Desk
 
@@ -821,3 +821,33 @@ Le seul échec du gate est dans `cargo clippy --workspace --all-targets --all-fe
 Le fix ne modifie aucun code de production. Le canari teste désormais d'abord `Option::is_some()` puis extrait la valeur avec `let-else`; la branche impossible retourne seulement après l'assertion dynamique. Aucun `panic!`, `unreachable!`, `unwrap()` ou `expect()` n'est introduit.
 
 Non-claims : aucune modification du runtime Desk, du monitoring, des routes, de Config, Transport, Store, Worker, Common RAW, acquisition, replay, repair ou politique health/fault.
+### `pre.012-fix.004` — diagnostic sémantique des conflits RAW inter-routes
+
+Le gate opérateur de `pre.012-fix.003` compile et teste proprement la tranche puis reproduit deux faults Mainnet distincts sur Yellowstone : un premier terminal `content_conflict` avec `content_conflict_total=13` pendant l'exécution simultanée de Yellowstone + HTTP Block Polling, puis un `source_failed / onchain_transport.grpc_backpressure_overflow` sur un run ultérieur. Le premier fault ne peut pas être expliqué par le cache de convergence interne d'un Worker : les deux routes Desk sont deux Workers indépendants qui partagent le même Store, et le conflit peut donc être détecté au niveau PostgreSQL lorsqu'une même identité canonique `(network, signature)` arrive avec un contenu différent.
+
+Le fix ajoute un diagnostic fail-closed au point exact où PostgreSQL possède les deux versions. Avant de renvoyer le même `store_api.raw_conflict`, le backend journalise uniquement un masque borné et sans valeur métier :
+
+```text
+slot_mismatch
+block_time_mismatch
+format_id_mismatch
+format_version_mismatch
+content_hash_mismatch
+payload_bytes_mismatch
+payload_diagnostic_available
+transaction_mismatch
+meta_mismatch
+version_mismatch
+transaction_index_mismatch
+payload_other_mismatch
+meta_mismatch_fields
+```
+
+Pour RAW transaction v1, `meta_mismatch_fields` compare uniquement une liste fixe de champs connus : `err`, `status`, `fee`, `preBalances`, `postBalances`, `innerInstructions`, `logMessages`, `preTokenBalances`, `postTokenBalances`, `rewards`, `loadedAddresses`, `returnData`, `computeUnitsConsumed`, `costUnits`, `accounts`. Toute extension inconnue est réduite au marqueur statique `other`; aucun nom arbitraire ni valeur JSON distante n'est copié dans les logs.
+
+Une seconde ligne de diagnostic lit au mieux l'observation durable la plus ancienne de la transaction conflictuelle et compare uniquement la provenance logique sûre avec l'observation entrante : `provider`, `protocol`, `acquisition_method`, `endpoint_id`, `commitment`. Signature, hash, payload, bytes, source payload hash, capture session et filter id ne sont jamais journalisés. Une impossibilité de lire cette observation de diagnostic ne modifie pas le fault original.
+
+Ce fix n'altère ni l'identité canonique, ni la comparaison d'égalité, ni la politique de conflit, ni le Store schema, ni la stratégie d'acquisition. `serde_json` est utilisé uniquement dans le backend PostgreSQL pour classifier les composants du payload RAW v1 déjà canonique au moment d'un conflit.
+
+Le prochain live Yellowstone + HTTP Block Polling doit permettre de distinguer immédiatement un désaccord de `slot`/`block_time`, de transaction wire, de transaction index, de version ou d'un sous-ensemble précis de `meta` (par exemple `logMessages` ou `rewards`).
+