v0.5.2-pre.007

prompts/001.README.md

@@ -1,8 +1,8 @@
 <!-- file: prompts/001.README.md -->
-<!-- version: 5 -->
+<!-- version: 6 -->
 
 # Prompts actifs
 
 Ce répertoire contient uniquement les prompts nécessaires aux prochaines versions fonctionnelles. Les prompts clôturés sont archivés sous `olddocs/archivekbot3/prompts/`.
 
-- [`031_v0_5_2_ks_wallet_restructuring.md`](031_v0_5_2_ks_wallet_restructuring.md) : restructuration de `ks-wallet`, format persistant versionné, séparation identité/secret/signature, migration legacy et sécurité des futurs consommateurs.
+- [`032_v0_5_3_ks_store_normalization.md`](032_v0_5_3_ks_store_normalization.md) : audit et normalisation de `ks-store`, temporalité/provenance/idempotence, migration `kb_sol_*` -> `k_sol_*` et préparation du stockage pour les futurs faits de trading.

prompts/031_v0_5_2_ks_wallet_restructuring.md

@@ -1,291 +0,0 @@
-<!-- file: prompts/031_v0_5_2_ks_wallet_restructuring.md -->
-<!-- version: 1 -->
-
-# Khadhroony Bot3 — `0.5.2` — restructuration de `ks-wallet`
-
-## Mission
-
-Reprendre `khadhroony-bot3` après la clôture validée de `0.5.1` et restructurer `ks-wallet` comme composant Solana généraliste réutilisable par les futurs exécuteurs, workers et applications.
-
-`0.5.2` doit stabiliser les frontières entre :
-
-1. identité publique d’un wallet ;
-2. matériau secret persistant ;
-3. état verrouillé/déverrouillé ;
-4. capacité de signature ;
-5. sélection/configuration d’un wallet par les consommateurs ;
-6. migration du format legacy déjà utilisé par le workspace.
-
-Cette version est un chantier wallet/sécurité. Elle ne doit pas ouvrir `0.5.3` sur `ks-store`, `0.5.4` sur les scénarios/exécuteurs, ni une nouvelle couverture Anchor/DEX.
-
-## Base validée héritée de `0.5.1`
-
-La base attendue possède notamment :
-
-- les dix crates Solana généralistes sous `ks-*` / `ks_*` ;
-- `kb-app-demo-desktop` dans le domaine Bot ;
-- variables Solana sous `KS_*` et contrats applicatifs Bot sous `KB_*` ;
-- documents spécialisés `logging.config.json`, `transport.config.json`, `listeners.config.json`, `store.config.json`, `wallet.config.json` et `execution.config.json` ;
-- exemples conformes sous `config/exemples/` et schémas sous `config/schemas/` ;
-- composition propre au desktop via `config/kb-app-demo-desktop.default.config.json` ;
-- classification `Secret > Internal > Public` ;
-- contrats source/runtime sensibles backend-only ;
-- TS-RS absent de `ks-config` et `ks-lib`, avec DTO Tauri possédés par les applications ;
-- URLs résolues retirées des snapshots transport et des surfaces Tauri.
-
-Ne pas réintroduire un type `ks-wallet` directement sérialisable vers le frontend par commodité.
-
-## Invariants de namespace
-
-Le workspace, le dépôt et le répertoire racine restent `khadhroony-bot3`.
-
-`ks-wallet` appartient au domaine Khadhroony Solana. Ses variables utilisent donc `KS_*`. Une future application Bot peut utiliser `KB_*` uniquement pour ses propres choix applicatifs, jamais pour renommer artificiellement un contrat wallet généraliste.
-
-Les secrets wallet ne doivent jamais être placés dans :
-
-- un fichier de configuration source ;
-- `KS_PUBLIC_*` ou `KB_PUBLIC_*` ;
-- un payload Tauri ;
-- un diagnostic normal ;
-- un log ou une erreur ;
-- un `Debug` automatique ;
-- un binding TS-RS générique.
-
-## Première prerelease obligatoire : plan et caractérisation
-
-`0.5.2-pre.001` doit être un plan/brainstorm/inventaire. Ne pas commencer par introduire un nouveau format chiffré.
-
-La première prerelease doit au minimum :
-
-- relire `ks-wallet/README.md`, `USAGE.md`, `TODO.md`, `CHANGELOG.md` et tout son code ;
-- inventorier tous les consommateurs de `ks-wallet` dans le workspace ;
-- inventorier les chemins de configuration wallet et variables d’environnement ;
-- caractériser exactement le format legacy `<alias>.json` actuellement utilisé ;
-- caractériser les permissions de fichier et comportements Unix actuels ;
-- inventorier création temporaire, persistance, lecture, validation, signature et erreurs ;
-- relever toutes les dérivations `Clone`, `Debug`, `Serialize`, conversions ou getters pouvant copier/afficher du matériau sensible ;
-- inventorier les usages directs de `solana_keypair`, `solana_signer::Signer`, `Arc<dyn Signer>` ou équivalents ;
-- définir les besoins réels multi-wallets et multi-profils sans inventer une UI non demandée ;
-- définir un contrat de migration et de rollback avant toute écriture du nouveau format ;
-- proposer un découpage borné des prereleases de `0.5.2` ;
-- créer un plan temporaire `0.5.2` sous `docs/plans/`, qui sera archivé dans la dernière prerelease.
-
-Le plan doit être validé avant la première migration de format.
-
-## Format legacy à préserver comme entrée de migration
-
-Le workspace possède actuellement un format persistant legacy basé sur le tableau JSON standard d’octets du keypair Solana.
-
-Avant de le remplacer :
-
-- écrire des tests de caractérisation à partir d’une fixture synthétique ;
-- vérifier le nommage `<alias>.json` et les contraintes d’alias ;
-- vérifier les permissions de fichier existantes ;
-- vérifier le comportement en cas de fichier absent, corrompu, incomplet ou déjà présent ;
-- vérifier que la clé publique obtenue après import correspond exactement à l’ancienne ;
-- interdire toute réécriture destructive sans preuve que la migration est complète.
-
-Ne jamais utiliser une vraie clé privée de l’opérateur comme fixture.
-
-## Cible conceptuelle du nouveau contrat
-
-La solution exacte doit être décidée après audit, mais les frontières suivantes doivent être explicites.
-
-### Identité publique
-
-Une identité publique peut contenir par exemple :
-
-- alias logique ;
-- clé publique ;
-- type/source de wallet ;
-- état disponible/verrouillé ;
-- métadonnées non sensibles strictement nécessaires.
-
-Elle ne contient jamais les octets secrets.
-
-### Matériau secret
-
-Le matériau secret :
-
-- reste encapsulé ;
-- n’implémente pas `Debug` en clair ;
-- n’est pas sérialisé arbitrairement ;
-- doit pouvoir être zéroïsé lorsque le type et les dépendances le permettent ;
-- n’est jamais exposé par getter de bytes public sans justification explicite.
-
-### Capacité de signature
-
-Les consommateurs doivent dépendre d’une capacité de signature bornée plutôt que d’un accès aux octets privés.
-
-Évaluer notamment :
-
-- trait propre à `ks-wallet` ou adaptation stricte à `solana_signer::Signer` ;
-- ownership et thread-safety ;
-- passage vers les exécuteurs sans rendre le secret clonable ;
-- session déverrouillée de durée bornée si un chiffrement persistant est introduit.
-
-### État verrouillé/déverrouillé
-
-Si le stockage chiffré est retenu, définir explicitement :
-
-- état verrouillé ;
-- opération de déverrouillage ;
-- durée ou portée de la session ;
-- invalidation/lock ;
-- changement de secret ;
-- comportement après erreur ;
-- absence de secret dans les erreurs et logs.
-
-Ne pas faire du booléen `is_unlocked` une preuve suffisante si la capacité de signature peut être désynchronisée.
-
-## Chiffrement persistant
-
-Ne choisir l’algorithme, le KDF, le nonce et le format de conteneur qu’après inventaire des dépendances déjà présentes et vérification des exigences de sécurité.
-
-Le workspace possède déjà notamment `argon2`, `chacha20poly1305` et `zeroize` dans ses dépendances. Cela ne signifie pas qu’ils doivent être utilisés aveuglément ni avec des paramètres arbitraires.
-
-Le format persistant, s’il change, doit être :
-
-- versionné ;
-- auto-identifiable ;
-- strictement validé ;
-- extensible sans ambiguïté ;
-- écrit atomiquement ;
-- compatible avec une stratégie de migration/rollback ;
-- documenté avant d’être considéré stable.
-
-Ne pas stocker le secret de chiffrement dans `wallet.config.json` ni dans un fichier versionné.
-
-## Import, export, backup et restore
-
-Ces capacités ne sont pas automatiquement obligatoires dans la première tranche de code. Leur besoin et leur surface doivent être décidés dans le plan.
-
-Si elles sont retenues :
-
-- distinguer import legacy, import du nouveau conteneur et export public ;
-- éviter toute exportation privée implicite ;
-- définir les permissions de fichiers et écriture atomique ;
-- refuser l’écrasement silencieux ;
-- définir les collisions d’alias et de pubkey ;
-- tester rollback et corruption ;
-- ne jamais écrire de keypair secret dans les logs ou diagnostics.
-
-## Multi-wallets et profils
-
-`wallet.config.json` possède déjà une racine globale et des profils.
-
-`0.5.2` doit décider proprement :
-
-- si un profil sélectionne un alias unique ou un ensemble de wallets ;
-- comment un futur worker choisit son wallet sans dépendre de `kb-app-demo-desktop` ;
-- comment un exécuteur demande un signer sans connaître le stockage ;
-- comment plusieurs wallets sont listés et sélectionnés sans exposer leur matériau secret ;
-- comment les wallets temporaires et persistants coexistent.
-
-Ne pas transformer `ks-config` en gestionnaire de secrets. `ks-config` peut sélectionner des identités/aliases publics ou internes, mais le matériau secret appartient à `ks-wallet` et/ou à la source de secret dédiée retenue.
-
-## Tauri et surfaces publiques
-
-`ks-wallet` ne doit pas reprendre TS-RS simplement parce que le desktop souhaite afficher une liste de wallets.
-
-Si le desktop a besoin d’une surface UI :
-
-```text
-ks-wallet runtime
-    -> wrapper/DTO kb-app-demo-desktop
-    -> TS-RS
-    -> frontend
-```
-
-Les DTO applicatifs peuvent exposer uniquement les informations explicitement sûres, par exemple alias, pubkey et état logique.
-
-Prévoir des canaris de non-divulgation semblables à ceux de `0.5.1`.
-
-## Erreurs, logs et diagnostics
-
-Toute nouvelle erreur liée au wallet doit être conçue pour être utile sans révéler :
-
-- octets de secret ;
-- phrase/password ;
-- contenu chiffré ;
-- chemin local complet si ce chemin n’est pas explicitement un diagnostic interne ;
-- valeur d’une variable `KS_SECRET_*` ;
-- représentation `Debug` d’un keypair/signer.
-
-Les logs peuvent identifier une opération et un alias/public key lorsque cette donnée est autorisée, mais ne doivent pas concaténer les structures runtime sensibles.
-
-## Tests minimums à prévoir
-
-Le plan `pre.001` doit définir précisément les tranches, mais `0.5.2` devra couvrir au minimum :
-
-- caractérisation du format legacy ;
-- import legacy préservant la pubkey ;
-- corruption/troncature/version inconnue ;
-- permissions privées ;
-- écriture atomique et refus d’écrasement ;
-- collisions d’alias/pubkey ;
-- persistance et réouverture ;
-- état verrouillé/déverrouillé si applicable ;
-- signature correcte sans exposition des bytes ;
-- absence de secret dans `Debug`, `Display`, erreurs, logs et DTO ;
-- concurrence/thread-safety des signers réellement utilisés ;
-- API externe crate-root de `ks-wallet` ;
-- intégration avec `ks-config` sans dépendance inverse vers une application.
-
-Les tests avec fichiers doivent utiliser des répertoires temporaires et des clés synthétiques. Aucun secret réel ne doit être requis.
-
-## Découpage indicatif à confirmer par `pre.001`
-
-Le numéro exact peut évoluer après inventaire, mais l’ordre conceptuel attendu est :
-
-1. `pre.001` — plan, caractérisation legacy, threat model et inventaire des consommateurs ;
-2. tranche de contrats publics/identité/signature avant modification du stockage ;
-3. tranche de conteneur persistant versionné et migration legacy ;
-4. tranche chiffrement/verrouillage si retenue après validation du format ;
-5. tranche multi-wallet/import-export/backup uniquement si confirmée par le plan ;
-6. intégration `ks-config` / consommateurs / desktop via DTO sûrs ;
-7. dernière prerelease — documentation, audits, TODO, archivage du plan/prompt et préparation de `0.5.3`.
-
-Un correctif `fix-XXX` conserve le numéro de prerelease et sa numérotation recommence à `fix-001` pour chaque prerelease.
-
-## Hors périmètre de `0.5.2`
-
-- migration SQL `kb_sol_*` -> `k_sol_*` ;
-- refonte temporelle/provenance de `ks-store` ;
-- centralisation générale des scénarios `0.5.4` ;
-- ajout de protocoles Anchor/DEX ;
-- stockage d’un secret wallet dans PostgreSQL sans décision architecturale dédiée ;
-- hardware wallets, remote signers, KMS/HSM ou Ledger tant qu’ils ne sont pas explicitement priorisés ;
-- mécanisme universel de secret manager pour toutes les crates.
-
-## Validation de référence
-
-Après chaque delta Rust ou contractuel :
-
-```bash
-cargo fmt --all
-cargo check --workspace
-cargo clippy --all-targets
-python3 scripts/audit_rust_workspace_rules.py
-cargo test --workspace
-```
-
-Lorsque le desktop est modifié :
-
-```bash
-cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
-```
-
-Les scripts npm de build/dev ne sont jamais lancés directement.
-
-## Dernière prerelease de `0.5.2`
-
-La dernière prerelease doit :
-
-- réconcilier tous les contrats wallet et consommateurs ;
-- finaliser README/USAGE/TODO/changelogs/guides ;
-- supprimer les TODO réellement fermés et reporter les autres vers une version identifiée ;
-- exécuter les validations finales ;
-- reprendre les décisions durables dans le ROADMAP et les documents normatifs ;
-- archiver le plan `0.5.2` et ce prompt sous `olddocs/archivekbot3/` ;
-- préparer le prompt de `0.5.3` pour l’audit/normalisation de `ks-store`.

prompts/032_v0_5_3_ks_store_normalization.md

@@ -0,0 +1,392 @@
+<!-- file: prompts/032_v0_5_3_ks_store_normalization.md -->
+<!-- version: 4 -->
+
+# Khadhroony Bot3 — `0.5.3` — audit et normalisation de `ks-store`
+
+## Mission
+
+Reprendre `khadhroony-bot3` après la clôture validée de `0.5.2` et auditer puis normaliser `ks-store` avant l'extension massive des décodages/matérialisations Solana et, à court terme, l'arrivée des surfaces Anchor/DEX nécessaires au trading. `ks-lib` reste généraliste : il doit pouvoir décoder et matérialiser le maximum de transactions, signatures, comptes et événements Solana issus de Program IDs multiples et évolutifs, qu'ils concernent le trading, les metadata, les tokens, le staking, l'administration, la conformité ou d'autres domaines.
+
+`0.5.3` doit traiter comme un même chantier cohérent quatre objectifs structurants et leurs conséquences :
+
+1. **renommer durablement les tables Solana** du préfixe historique `kb_sol_*` vers `k_sol_*` ;
+2. **auditer puis figer le contrat structurel des tables existantes**, afin qu'une table déclarée stable ne doive plus recevoir ultérieurement de colonne oubliée, de changement de type, de nullabilité, de clé ou de sémantique ;
+3. **mettre `ks-store` aux conventions du workspace** : frontières de modules, exports crate-root, DTO/models, erreurs, configuration, logging, tests, documentation et règles Rust ;
+4. **rendre la frontière de stockage indépendante du moteur concret** : les autres crates consomment des contrats génériques de `ks-store` et ne doivent pas appeler les modules/fonctions PostgreSQL. `ks-store` reçoit la configuration du backend et possède seul la connexion, le routage et l'implémentation spécifique au moteur.
+
+Ces quatre objectifs impliquent aussi l'audit des temporalités blockchain/persistance, de la provenance, de l'idempotence, des migrations, index et requêtes, ainsi que la préparation additive de faits canoniques Solana couvrant plusieurs domaines. Le trading est une priorité de court terme, pas la définition du périmètre de `ks-store`.
+
+Cette version reste un chantier stockage. Elle ne doit pas ouvrir `0.5.4` sur la réconciliation générale des scénarios/exécuteurs, ni `0.6.x` sur Anchor, ni Meteora/Raydium/Pump/Orca/Jupiter.
+
+## Base validée héritée de `0.5.2`
+
+La base attendue possède notamment :
+
+- onze crates Solana généralistes sous `ks-*` / `ks_*`, dont `ks-wallet-demo-scenarios`, plus `kb-app-demo-desktop` côté Bot ;
+- `kb-app-demo-desktop` conservé côté Bot ;
+- configuration spécialisée et composable, avec `KS_*` pour les contrats Solana et `KB_*` pour les contrats réellement applicatifs ;
+- séparation source/runtime/public des données sensibles ;
+- `ks-wallet` multi-wallet avec conteneur natif `.kswallet`, Argon2id + XChaCha20-Poly1305, sélection par alias, migration legacy, imports/exports secrets explicites et validation password réutilisable via `ks-wallet-demo-scenarios` ;
+- `ks-lib` indépendant du stockage wallet et consommant uniquement une capacité `Signer` ;
+- transport HTTP/WS généraliste dans `ks-onchain-transport` ;
+- pipeline/replay/materialisation existants sur PostgreSQL via `ks-store` ;
+- tables historiques encore préfixées `kb_sol_*`, volontairement laissées à `0.5.3` ;
+- séparation entre faits Solana généralistes et futur domaine applicatif Bot.
+
+Ne pas annuler les frontières de sécurité/configuration validées en `0.5.1`/`0.5.2` pour simplifier le stockage.
+
+## Lectures obligatoires avant toute proposition
+
+1. `README.md`, `ROADMAP.md`, `CHANGELOG.md`, `RULES.md` et ce prompt ;
+2. toutes les règles actives sous `docs/rules/` ;
+3. `docs/architecture/STORAGE_ARCHITECTURE.md`, `PIPELINE_ARCHITECTURE.md`, `ARCHITECTURE.md`, `CRATE_MAP.md` et `SURFACE_CRATE_MATRIX.md` ;
+4. `ks-store/README.md`, `USAGE.md`, `TODO.md`, `CHANGELOG.md` et tout le code de `ks-store` ;
+5. toutes les migrations SQL, constantes de noms de tables, repositories et requêtes ;
+6. DTO persistés/relus par `ks-pipeline`, `kb-app-demo-desktop` et les tests d'API externe ;
+7. scripts de validation, fixtures PostgreSQL, rapports Devnet/Mainnet et historiques de migrations pertinents ;
+8. documents archivés `0.5.0`/`0.5.1` uniquement comme historique lorsque la décision actuelle n'est pas déjà portée par le ROADMAP ou l'architecture active.
+
+Avant de renommer une table ou un champ, rechercher son usage dans tout le workspace, les migrations, requêtes, tests, fixtures, scripts et documentation.
+
+## Principe de gel structurel des tables
+
+`0.5.3` est la fenêtre prévue pour corriger **avant gel** les lacunes structurelles des tables déjà créées. L'exemple déjà identifié est l'absence de temps on-chain/block time là où cette information doit être conservée.
+
+Pour chaque table existante, `0.5.3-pre.001` doit déterminer avant modification :
+
+- son propriétaire fonctionnel et son rôle durable ;
+- ses colonnes requises pour les usages actuels **et raisonnablement prévisibles** ;
+- les temporalités nécessaires ;
+- les clés primaires, étrangères, uniques et d'idempotence ;
+- les types, nullabilités et unités ;
+- la provenance nécessaire ;
+- les besoins de replay et de rétention ;
+- si elle doit être conservée, reconstruite, fusionnée, remplacée ou supprimée avant le gel.
+
+Après clôture de `0.5.3`, une table marquée stable doit être considérée comme un **contrat append-only au niveau du schéma global** :
+
+- pas d'ajout/suppression/renommage de colonne ;
+- pas de changement de type ou de nullabilité ;
+- pas de changement de clé primaire, clé étrangère ou contrainte métier ;
+- pas de changement de sémantique d'une colonne existante.
+
+Les nouvelles fonctionnalités doivent préférer **de nouvelles tables reliées aux contrats existants** plutôt qu'un remodelage d'une table gelée. Les objets physiques d'optimisation tels que les index doivent être distingués du contrat logique des tables dans le plan `pre.001`, et toute politique d'évolution après gel doit être explicitement documentée.
+
+La règle ne signifie pas qu'il faut inventer toutes les tables futures : elle impose que chaque table déclarée stable ait été suffisamment auditée pour ne pas devoir être réparée fonctionnellement quelques versions plus tard.
+
+## Première prerelease obligatoire : plan et audit
+
+`0.5.3-pre.001` doit être un plan/brainstorm/audit. Elle ne doit pas commencer par renommer physiquement les tables.
+
+Elle doit produire au minimum :
+
+- inventaire exhaustif des tables et migrations actives ;
+- inventaire des préfixes `kb_sol_*`, de leurs propriétaires et de leurs consommateurs ;
+- matrice table -> DTO -> repository/query -> pipeline/desktop ;
+- inventaire des colonnes temporelles et de leur sémantique réelle ;
+- inventaire des champs de provenance, hash, version, processor, source/provider et états de traitement ;
+- audit d'idempotence et des clés uniques ;
+- audit des index existants versus requêtes réelles ;
+- audit des limites/pagination et des conversions `u64` <-> PostgreSQL `BIGINT` ;
+- classification des colonnes devant être corrigées **avant gel**, avec justification table par table ;
+- matrice de gel structurel indiquant pour chaque table son état `à corriger`, `à remplacer`, `à supprimer` ou `stable/frozen` ;
+- stratégie de migration/reconstruction des bases Devnet/Mainnet avant `0.6.x` ;
+- stratégie explicite `kb_sol_* -> k_sol_*` ;
+- audit des appels PostgreSQL hors `ks-store` et plan de suppression de toute dépendance backend-spécifique depuis les autres crates ;
+- matrice API générique `DTO/model -> store contract -> backend implementation` ;
+- stratégie de configuration du backend possédée par `ks-store` ;
+- inventaire des domaines de faits Solana déjà matérialisés ou raisonnablement prévisibles : core/transactions, comptes et balances, token/SPL, metadata, lifecycle, staking, administration/autorités, audit/compliance, risques, programmes, trading/marchés et autres domaines justifiés par les Program IDs couverts ;
+- identification des modèles canoniques suffisamment stables pour être créés de manière additive, sans supposer que tout doit entrer dans une table générique unique ;
+- pour la priorité trading : pools de liquidité/AMM, order books si leur structure ne peut pas être unifiée proprement, marchés/paires, swaps/trades, liquidité, positions, réserves et séries temporelles ;
+- matrice de normalisation `Program ID / source -> observation décodée -> matérialiseur -> DTO canonique -> table métier`, interdisant aux noms/champs spécifiques d’un programme ou d’un DEX de devenir par défaut le schéma public de stockage ;
+- plan de prereleases borné jusqu'à la clôture `0.5.3` ;
+- plan temporaire `docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md` à archiver dans la dernière prerelease.
+
+Le plan doit être validé avant toute migration SQL massive.
+
+## Temporalité à auditer explicitement
+
+Ne pas utiliser un seul timestamp ambigu pour plusieurs concepts.
+
+Distinguer selon les données réellement disponibles :
+
+- `slot` ;
+- `block_time` ou temps de transaction fourni par Solana ;
+- temps d'observation/acquisition par le transport ;
+- temps d'insertion en base ;
+- temps de mise à jour/reprocessing ;
+- temps éventuel de matérialisation.
+
+Le plan doit dire pour chaque table quelles temporalités sont pertinentes, leur nullabilité et leur source de vérité.
+
+Ne pas inventer un `block_time` lorsqu'il n'est pas présent dans la donnée canonique.
+
+## Provenance
+
+Chaque donnée persistée doit permettre de répondre, lorsque nécessaire, à :
+
+- quelle transaction/signature/slot l'a produite ;
+- quelle entrée canonique a été décodée ;
+- quel décodeur/version a produit l'observation ;
+- quel matérialiseur/version a produit le fait ;
+- quel provider/transport a fourni la donnée brute lorsqu'il s'agit d'une donnée d'acquisition ;
+- si le résultat est courant, supersédé, pending, failed ou replay-requested selon le domaine concerné.
+
+Éviter de dupliquer la provenance dans toutes les tables si une relation canonique existante permet de la résoudre efficacement.
+
+## Idempotence et replay
+
+Auditer les contrats existants avant modification :
+
+- clés d'idempotence ;
+- hash d'input ;
+- version de processor ;
+- replacement/replay ;
+- transaction atomique entre observation, couverture, ledger et matérialisation ;
+- comportement en cas de reprise après erreur ;
+- effets d'un replay forcé sur les lignes déjà présentes.
+
+Une migration ne doit pas affaiblir les garanties actuelles simplement pour simplifier le schéma.
+
+## Migration `kb_sol_* -> k_sol_*`
+
+La cible durable des tables généralistes Solana est :
+
+```text
+k_sol_*
+```
+
+Le préfixe :
+
+```text
+kb_*
+```
+
+reste réservé aux données dont le propriétaire fonctionnel est réellement le domaine Bot.
+
+Avant le renommage :
+
+- inventorier toutes les tables `kb_sol_*` ;
+- vérifier qu'elles sont bien généralistes Solana ;
+- rechercher toutes les références SQL/textuelles ;
+- décider migration incrémentale versus reconstruction propre des bases de développement ;
+- définir le comportement des migrations sur une base existante et sur une base vide ;
+- vérifier noms d'index, contraintes et séquences éventuelles ;
+- ajouter des tests empêchant le retour de noms `kb_sol_*` actifs après clôture.
+
+Ne pas renommer une table spécifique Bot en `k_sol_*` par simple proximité avec Solana.
+
+## Index et requêtes
+
+Les index doivent être justifiés par les requêtes actuelles ou par un besoin futur suffisamment stable.
+
+Auditer notamment :
+
+- recherche par signature ;
+- slot/ranges ;
+- program id ;
+- processor/version/state ;
+- address/account ;
+- mint/token account lorsque ces clés existent déjà dans les faits ;
+- pagination stable ;
+- requêtes de replay ;
+- futures extractions temporelles destinées au trading/research.
+
+Éviter les index spéculatifs massifs sur des colonnes qui ne sont pas encore produites par les matérialisateurs.
+
+## Préparation additive des faits canoniques Solana
+
+`ks-store` ne doit pas être conçu comme une base de trading. Il est la frontière de persistance généraliste des faits Solana produits par les décodeurs et matérialiseurs de `ks-lib`. Le trading est la priorité fonctionnelle immédiate, mais seulement un domaine parmi d'autres.
+
+Principe durable :
+
+> Un Program ID ou un protocole est une **source de sémantique et de provenance**. Il ne devient pas automatiquement le propriétaire d'une table. Les tables sont définies par des faits/concepts canoniques suffisamment stables et réutilisables.
+
+Les matérialiseurs portent la normalisation : ils convertissent comptes, événements, instructions, noms de champs, unités et conventions propres à chaque programme vers des DTO/models canoniques de `ks-store`. Une différence de nom, de wire format, de version de programme ou de représentation protocolaire ne justifie pas à elle seule une nouvelle table.
+
+Le plan `0.5.3-pre.001` doit donc auditer le stockage par **domaines de faits**, notamment :
+
+- transaction/core, instructions, comptes, balances et lifecycle ;
+- tokens/SPL, mints, token accounts, autorités et extensions ;
+- metadata on-chain et états associés ;
+- programmes, loaders, administration et autorités ;
+- staking/vote et autres états natifs ;
+- audit, compliance, risques et annotations ;
+- trading/marchés ;
+- tout autre domaine durable découvert dans les Program IDs couverts par `ks-lib`.
+
+Ces catégories ne sont pas une taxonomie rigide ni une obligation de table unique par domaine. `pre.001` doit déterminer ce qui peut être unifié et ce qui doit rester séparé **par nature du fait et invariants métier**, jamais par commodité liée au Program ID.
+
+### Priorité court terme : faits de trading
+
+Pour le trading, auditer au minimum des concepts canoniques comme :
+
+- identité de marché/paire lorsque ce concept peut être partagé ;
+- pools de liquidité / AMM ;
+- order books lorsque leur état ne peut pas être représenté proprement par le même contrat que les pools ;
+- réserves et états de liquidité ;
+- positions/liquidité concentrée lorsqu'un modèle générique durable existe ;
+- swaps/trades/exécutions ;
+- prix, volumes et métriques dérivées ;
+- séries temporelles/OHLC/candles ;
+- relations de routing et graphes multi-pools/multi-marchés.
+
+Meteora, Raydium, Pump, Orca, Jupiter ou tout autre DEX alimentent ces concepts via leurs décodeurs/matérialiseurs. Ils ne doivent pas créer des familles de tables par protocole. De la même manière, un programme de metadata ou de staking ne doit recevoir une table spécifique que si le **fait stocké** est réellement spécifique et durable, pas simplement parce que son Program ID est différent.
+
+Par exemple, une table canonique commune de marché peut porter l'identité commune d'une paire, tandis que l'état d'un AMM/liquidity pool et celui d'un order book peuvent rester dans deux tables spécialisées si leurs invariants sont réellement incompatibles. Cette décision doit découler des faits à stocker, pas du nom du protocole.
+
+Lorsque des concepts plus spécialisés apparaîtront plus tard (ticks, bins, positions, courbes, ordres, niveaux de carnet, états metadata particuliers, gouvernance, etc.), ils devront eux aussi être modélisés par concept réutilisable autant que possible. Une spécialisation est acceptable lorsqu'elle représente une structure métier réellement différente ; une spécialisation nommée d'après le protocole ou le Program ID ne l'est pas par défaut.
+
+`0.5.3` **peut créer dès maintenant de nouvelles tables canoniques** pour une fonctionnalité pas encore consommée si leur contrat est suffisamment stable et backend-agnostique. Une table candles/OHLC ou une frontière canonique liquidity-pool/order-book sont des candidats à auditer, pas des obligations automatiques.
+
+La décision doit respecter quatre règles :
+
+1. ne pas modifier une table gelée pour y greffer plus tard une nouvelle fonctionnalité ;
+2. préférer une table par fait/concept canonique à une table par protocole ou Program ID ;
+3. faire porter aux matérialiseurs la traduction `programme/protocole -> modèle canonique`, tout en conservant la provenance permettant de retrouver le programme/source/version d'origine ;
+4. ne pas sur-généraliser des concepts réellement distincts uniquement pour réduire le nombre de tables.
+
+Il ne doit donc pas exister de stratégie de stockage fondée sur des familles `meteora_*`, `raydium_*`, `pump_*`, `orca_*`, `jupiter_*`, etc. Cette règle est un exemple du principe plus général : la provenance programme/protocole ne doit pas devenir le découpage primaire du schéma de stockage.
+
+## Frontière générique de stockage
+
+`ks-store` possède la frontière de persistance. Les autres crates ne doivent pas connaître le moteur concret utilisé derrière cette frontière.
+
+À la clôture de `0.5.3` :
+
+- `ks-pipeline`, `kb-app-demo-desktop` et toute autre crate consommatrice manipulent des DTO/models et des opérations génériques exposés par `ks-store` ;
+- aucune crate externe à `ks-store` n'appelle une fonction, un module, un type de pool ou une requête nommé/spécifique `postgres` ;
+- les types `sqlx::PgPool`, `sqlx::postgres::*` et équivalents backend-spécifiques ne traversent pas la frontière publique de `ks-store` ;
+- les repositories/ports publics décrivent les opérations de stockage en termes fonctionnels, pas en termes SQL/PostgreSQL ;
+- les implémentations PostgreSQL restent internes à `ks-store` ;
+- `ks-pipeline` conserve l'orchestration des traitements et ne possède pas la connexion à la base ;
+- `kb-app-demo-desktop` reste un consommateur/adaptateur et ne possède pas de logique PostgreSQL.
+
+Le design doit permettre de réimplémenter plus tard la même frontière avec PostgreSQL, MySQL, SQLite, RocksDB, Oracle ou un autre moteur sans réécrire les consommateurs. **`0.5.3` n'a pas l'obligation d'implémenter tous ces backends** : PostgreSQL reste le backend opérationnel actuel, mais l'API publique ne doit plus l'imposer.
+
+Le plan `pre.001` doit décider explicitement la forme de cette abstraction : traits/ports, store façade, repositories génériques, factories ou autre composition conforme aux règles du workspace. Ne pas introduire un `enum` backend géant dans toutes les crates consommatrices.
+
+## Configuration et possession des connexions
+
+La configuration du stockage appartient à `ks-store`/`ks-config` selon la frontière de configuration générale, mais **l'interprétation backend-spécifique et la création des connexions appartiennent à `ks-store`**.
+
+Le contrat doit permettre de sélectionner un type de backend et de fournir les paramètres nécessaires au moteur choisi, par exemple :
+
+```text
+backend = postgres | mysql | sqlite | rocksdb | oracle | ...
+```
+
+Les détails concrets (`URL`/DSN, credentials, fichier SQLite, répertoire RocksDB, options de pool, timeouts, TLS, etc.) ne doivent pas remonter dans les DTO métier ni être interprétés par `ks-pipeline`.
+
+Il faut auditer les fichiers `store.config.json`, schémas, exemples et composition existante pour déterminer la forme durable du contrat sans casser les conventions `KS_*`/`KS_SECRET_*`.
+
+## PostgreSQL actuel et sécurité
+
+PostgreSQL reste l'implémentation active et doit continuer à être entièrement testée pendant `0.5.3`. L'abstraction n'est pas une excuse pour réduire la couverture réelle du backend actuellement utilisé.
+
+Aucun DSN, password, secret ou valeur de configuration sensible ne doit apparaître dans les erreurs/logs normaux.
+
+Conserver le masquage des DSN et les frontières backend-only validées en `0.5.1`.
+
+Les tests PostgreSQL optionnels continuent d'utiliser les variables d'environnement prévues et ne doivent jamais embarquer de credential réel dans une fixture versionnée.
+
+## Tests minimums à prévoir
+
+Le plan `pre.001` doit préciser les tranches, mais `0.5.3` devra couvrir au minimum :
+
+- migration sur base vide ;
+- migration/reconstruction depuis le schéma historique retenu ;
+- absence de noms `kb_sol_*` actifs à la clôture ;
+- cohérence des contraintes/index après migration ;
+- idempotence et replay ;
+- rollback transactionnel des graphes Core/decode ;
+- pagination bornée ;
+- limites `BIGINT` / slots ;
+- provenance et temporalité, notamment conservation correcte du temps on-chain lorsqu'il existe ;
+- requêtes critiques par signature/program/slot/state ;
+- santé PostgreSQL ;
+- canaris de frontière prouvant que les crates externes n'utilisent aucun type/fonction/module PostgreSQL ;
+- API externe crate-root générique indépendante du backend ;
+- canaris empêchant DSN/secret dans diagnostics et erreurs ;
+- tests de configuration invalidant proprement un backend inconnu ou incomplet ;
+- tests garantissant que les tables déclarées gelées correspondent exactement au contrat documenté.
+
+## Validation standard
+
+À chaque delta Rust ou SQL significatif :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo clippy --all-targets
+python3 scripts/audit_rust_workspace_rules.py
+cargo test --workspace
+```
+
+Les tests PostgreSQL réels seront activés lorsque la tranche le nécessite et avec les variables locales appropriées.
+
+Le desktop n'est lancé avec :
+
+```bash
+cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
+```
+
+que lorsqu'une surface qu'il consomme réellement a changé.
+
+Ne jamais demander de lancer directement `npm run build` ou `npm run dev` ; Tauri pilote Vite.
+
+## Règles de développement à préserver
+
+- Rust 2024 ;
+- I/O async-first ;
+- pas de `unsafe`, `unwrap`, `expect`, `panic` en production ;
+- pas de `?` dans les commandes Tauri ;
+- imports `use` réservés aux traits selon les règles du projet ;
+- exports crate-root explicites ;
+- pas de `pub mod` ;
+- `missing_docs`, `unreachable_pub` et `forbid(unsafe_code)` préservés ;
+- en-têtes `file:` / `version:` mis à jour à chaque modification ;
+- Markdown en français pour la documentation projet ;
+- changelogs ordonnés par ordre chronologique décroissant ;
+- pas de `Cargo.lock` dans les archives delta.
+
+## Cycle des prereleases
+
+La première prerelease est le plan/audit détaillé.
+
+Les prereleases intermédiaires réalisent les migrations par tranches bornées et validables.
+
+Un correctif `delta-fix-XXX` ne fait jamais avancer le numéro de prerelease et son compteur repart à `fix-001` pour chaque prerelease.
+
+La dernière prerelease de `0.5.3` doit obligatoirement :
+
+- réconcilier les contrats et migrations ;
+- exécuter les audits finaux ;
+- mettre à jour README/USAGE/TODO/changelogs/guides ;
+- supprimer les TODO terminés ;
+- mettre à jour le ROADMAP ;
+- produire/mettre à jour le rapport final de validation ;
+- archiver le plan temporaire `0.5.3` et ce prompt `032` sous `olddocs/archivekbot3/` ;
+- préparer le prompt de la session `0.5.4` consacrée aux scénarios, exécuteurs et validations.
+
+## Hors périmètre de `0.5.3`
+
+- nouvelle refonte fonctionnelle de `.kswallet` ;
+- migration générale des keypairs de fixtures `wallets/temporary/**`, prévue avec `0.5.4` ;
+- correction de la régression de chargement de fixture Token-2022 observée en clôture `0.5.2`, prévue avec la réconciliation des scénarios/fixtures de `0.5.4` ;
+- centralisation générale des scénarios/exécuteurs (`0.5.4`) ;
+- infrastructure Anchor (`0.6.x`) ;
+- implémentation Meteora/Raydium/Pump/Orca/Jupiter (`0.7.x+`) ;
+- hardware wallet/KMS/HSM ;
+- renommage du workspace/repository `khadhroony-bot3`.
+
+## Résultat attendu
+
+À la fin de `0.5.3`, `ks-store` doit posséder :
+
+- les tables généralistes Solana sous `k_sol_*` ;
+- un contrat structurel audité et **gelé** pour chaque table stabilisée, incluant les temporalités on-chain nécessaires afin d'éviter des réparations fonctionnelles ultérieures ;
+- une stratégie additive où les nouvelles fonctionnalités créent de nouvelles tables au lieu de remodeler les tables gelées ;
+- une API publique conforme aux conventions du workspace et indépendante de PostgreSQL ;
+- PostgreSQL comme implémentation active encapsulée dans `ks-store`, remplaçable ultérieurement par un autre backend sans réécriture de `ks-pipeline` ou des autres consommateurs ;
+- une base suffisamment propre pour accueillir durablement les futurs faits Solana — trading prioritaire à court terme, mais aussi metadata, token, staking, administration, audit/compliance et autres domaines — sans dette historique de namespace ou de frontière de stockage.