0.3.16-pre.001

Cargo.toml

@@ -1,12 +1,12 @@
 # file: Cargo.toml
-# version: 637
+# version: 638
 
 [workspace]
 resolver = "3"
 members = ["crates/ksp-app-backfill-desk", "crates/ksp-app-config-desk", "crates/ksp-app-raw-transaction-ingest-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-store-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-job-api", "crates/ksp-job-backfill-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-raw-transaction-lib", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib", "crates/ksp-worker-api", "crates/ksp-worker-raw-transaction-ingest-lib"]
 
 [workspace.package]
-version = "0.3.15"
+version = "0.3.16-pre.1"
 edition = "2024"
 license = "MIT"
 repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

deltas/0.3.16/pre.001.md

@@ -0,0 +1,178 @@
+<!-- file: deltas/0.3.16/pre.001.md -->
+<!-- version: 1 -->
+
+# Delta `0.3.16-pre.001` — gate d'audit, architecture et sizing
+
+## Base requise
+
+```text
+v0.3.15
+commit 7328be6997399c513306f2f4c8cdf00bd8b22367
+workspace.package.version = 0.3.15
+```
+
+Ne pas appliquer sur une `0.3.15-pre.*`.
+
+## Objet
+
+Exécuter le gate obligatoire de lecture/audit/brainstorming/sizing défini par `prompts/035-V0_3_16_START_PROMPT.md` avant toute migration ou implémentation lourde de la résilience RAW.
+
+Cette tranche :
+
+- réaudite la fermeture stable `0.3.15` ;
+- réaudite les règles KSP applicables ;
+- inventorie les contrats Store/Worker/Transport/Config/Store Desk actuels ;
+- réaudite les sémantiques Solana RPC et PostgreSQL pertinentes ;
+- compare plusieurs modèles physiques ;
+- choisit le modèle conceptuel et les ownerships ;
+- définit les invariants de concurrence/rétention/résolution ;
+- recalibre le découpage des prereleases ;
+- ne crée aucune migration SQL finale et ne modifie aucun Rust.
+
+## Version workspace
+
+`Cargo.toml` :
+
+```text
+header version : 637 -> 638
+workspace      : 0.3.15 -> 0.3.16-pre.1
+```
+
+Aucune autre modification sémantique du `Cargo.toml` racine n'est prévue.
+
+## Fichiers ajoutés
+
+```text
+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
+```
+
+## Fichiers modifiés
+
+```text
+Cargo.toml
+```
+
+## Fichiers supprimés
+
+```text
+aucun
+```
+
+## Décisions principales
+
+### Variantes
+
+Modèle retenu : ledger de variantes V003 à identifiant surrogate, sélecteur canonique sidecar et conservation de `ksp_raw_transactions` comme projection canonique compatible V001.
+
+`content_hash` est un préfiltre/intégrité ; il n'est pas une preuve d'égalité à lui seul lorsque les bytes sont disponibles.
+
+### Observations
+
+Toute observation créée sous V003 devra pointer vers la variante réellement reçue.
+
+Les observations historiques dont le payload entrant n'a pas été conservé sont qualifiées legacy/unknown et ne sont jamais faussement rattachées à une variante native reconstruite.
+
+### Comparaison
+
+Relations internes retenues :
+
+```text
+Exact
+CompatibleLessComplete
+CompatibleMoreComplete
+Conflict
+Incomparable
+```
+
+Seule la troncature `logMessages` strictement prouvée autorise une dominance automatique en première implémentation.
+
+### Rétention
+
+Les variantes nécessaires au canonique courant, aux conflits ouverts, au rollback ou à la lignée synthétique peuvent être archivées mais restent protégées contre une purge irréversible tant que l'invariant dépend de leurs bytes.
+
+### Store retry
+
+Le backend Store classe les fautes `Transient/Terminal` de manière backend-neutral ; le Worker orchestre retry, backpressure, health et exhaustion.
+
+### Transport reconnect
+
+La reconnexion reste propriété de `ksp-onchain-transport-lib` et étend les mécanismes existants. Elle reste distincte du retry Store et ne prouve jamais la coverage.
+
+### Store Desk
+
+Inspection et résolution passent exclusivement par `ksp-store-lib`. Les actions futures sont typées et protégées par revision attendue.
+
+## Découpage recalibré
+
+La release est étendue jusqu'à une prévision souple `pre.022` avant `rel.001` afin de ne pas fusionner artificiellement migration, backend, convergence, rétention, Worker, Transport, Desk et gates de fermeture.
+
+Le détail est dans le plan `038`.
+
+## Hors périmètre
+
+Inchangé par rapport au prompt 035 :
+
+```text
+Backfill multi-route/multi-stratégie
+Backfill Desk multi-route
+RAW -> STRUCTURAL
+STRUCTURAL persistence
+DECODED / DOMAIN
+majority/provider authority
+free JSON merge
+Internet reconstruction as normal rollback
+second acquisition pipeline
+Worker <-> Backfill dependency
+```
+
+## Validations réellement exécutées lors de l'assemblage du delta
+
+L'environnement d'assemblage possède uniquement les fichiers du delta, pas le checkout complet `v0.3.15`.
+
+Sont exécutés sur l'archive produite :
+
+```text
+parse TOML du Cargo.toml delta
+vérification workspace.package.version = 0.3.16-pre.1
+vérification des headers file/version des quatre fichiers
+vérification newline finale
+vérification absence de lockfile/cache/secret dans le ZIP
+vérification inventaire ZIP exact
+```
+
+Ne sont pas déclarés PASS ici :
+
+```text
+cargo fmt/check/clippy/test workspace
+scripts/audit_rust_workspace_rules.py
+scripts/audit_markdown_tables.py du dépôt complet
+byte-compare de l'archive source v0.3.15
+```
+
+L'archive binaire source stable n'était pas matérialisable dans l'environnement d'assemblage. L'arbre/tag canonique et le commit de base ont été vérifiés via le dépôt public.
+
+## Gate demandé après application
+
+À exécuter par l'opérateur sur le checkout exact `v0.3.15` après application du delta :
+
+```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
+```
+
+Aucun test live/provider/PostgreSQL n'est requis par ce gate documentaire s'il n'est pas explicitement exécuté. Aucun `npm run build` n'est utilisé.
+
+## Prochaine tranche
+
+Après gate propre :
+
+```text
+0.3.16-pre.002
+```
+
+Objet prévu : contrats Store API backend-neutral pour variantes, relations de qualité, reason codes et outcomes de persistance, sans migration PostgreSQL anticipée.

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