v0.5.3-pre.005-fix010

docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md -->
-<!-- version: 9 -->
+<!-- version: 12 -->
 
 # Plan `0.5.3` — audit et normalisation de `ks-store`
 
@@ -47,7 +47,7 @@ Les décisions suivantes sont retenues pour les tranches suivantes :
 6. **`kb_sol_mat_events` reste le journal générique versionné des sorties de matérialisation**, mais son nom durable devient `k_sol_mat_outputs`, cohérent avec son rôle réel ; les projections métier spécialisées seront additives ;
 7. **aucune table DEX/trading n'est créée en `0.5.3`** : aucun chantier DEX n'a encore fourni les invariants nécessaires à un contrat SQL gelable ; lorsque ces matérialisations arriveront, les tables devront être génériques par fait/concept et non par protocole ;
 8. **aucune projection metadata N4 n'est créée en `0.5.3`**, mais deux cibles conceptuelles sont déjà retenues : asset/token metadata commune Metaplex + Token-2022 et program metadata distincte pour SPM ; elles seront ajoutées lorsque leurs premiers contrats queryables seront suffisamment audités, puis resteront plus évolutives que les fondations N1-N3 ;
-9. **les bases Devnet/Mainnet/test actuelles sont considérées destructibles pour `0.5.3`** : la cible est une reconstruction propre, pas une compatibilité in-place avec le schéma `0.5.2` ; l'ancien schéma doit être détecté/refusé plutôt que silencieusement mélangé au nouveau ;
+9. **`ks-store` ne possède et ne valide que ses ressources `k_sol_*` courantes** : une reconstruction des bases Devnet/Mainnet/test reste acceptable pour `0.5.3`, mais une base non vide, des tables applicatives étrangères ou d'anciens objets `kb_sol_*` peuvent coexister sans blocage tant qu'aucun contrat courant de `ks-store` ne les utilise ;
 10. **les ressources SQL PostgreSQL sont rangées sous `ks-store/migrations/postgres/`** et chaque fichier contient une seule instruction SQL ; les fonctions privées PostgreSQL utilisent `include_str!` pour exécuter la ressource correspondante ;
 11. **tables, contraintes/keys, index et opérations de maintenance (`DROP`, `TRUNCATE`) sont séparés** en ressources/fonctions explicites et assemblés par un orchestrateur d'initialisation PostgreSQL transactionnel ;
 12. **le DDL dupliqué en chaînes Rust disparaît** : le fichier SQL inclus est l'unique source du texte SQL exécuté ;
@@ -625,36 +625,39 @@ La migration ne fait pas un simple remplacement textuel. Elle doit couvrir :
 - documentation active ;
 - chaînes visibles du desktop.
 
-### 15.2 Base vide
+### 15.2 Base PostgreSQL hôte
 
-Une base vide est la **cible normale de `0.5.3`**.
+`ks-store` ne requiert pas une base vide et ignore les tables étrangères au contrat courant, y compris d'éventuels objets historiques `kb_sol_*`. `auto_initialize_schema` est un mécanisme d'évolution **additive seulement** du schéma géré.
 
-L'auto-initialisation PostgreSQL exécute l'orchestrateur des ressources SQL unitaires dans un ordre déterministe : tables, contraintes, index, puis vérification du snapshot logique. Le résultat final ne doit contenir aucun objet actif `kb_sol_*`.
+À l'ouverture, les ressources gérées déjà présentes sont contrôlées avant toute initialisation. Une définition existante incompatible (type/nullabilité/défaut de colonne, définition PK/FK ou définition d'index) est bloquante et n'est jamais modifiée implicitement. En revanche, une table, colonne, clé/contrainte ou index attendu mais absent peut être ajouté lorsque l'auto-initialisation est active. L'orchestrateur applique ces ajouts transactionnellement dans l'ordre tables -> colonnes -> contraintes -> index, puis revalide le contrat complet. Il n'exécute aucun retrait, renommage ni mutation d'une colonne existante. Une base hôte peut donc être un sur-ensemble du schéma `ks-store` sans devenir incompatible.
 
-### 15.3 Bases `0.5.2` Devnet/Mainnet/test
+### 15.3 Compatibilité du schéma géré
 
-La décision de session est de **supprimer et recréer** les bases actuelles. `0.5.3` n'investit donc pas dans une migration in-place des données historiques.
+`0.5.3` n'investit pas dans une migration in-place des données historiques `0.5.2`, mais leur simple présence ne constitue plus une erreur. Le comportement attendu est :
 
-Le comportement attendu est :
+1. table gérée trouvée + colonnes, clés et index compatibles -> `OK`, sans exécuter d'initialisation ;
+2. ressource gérée existante avec une définition incompatible -> `ERR`, même avec `auto_initialize_schema=true` ;
+3. table/colonne/clé/index géré absent + `auto_initialize_schema=false` -> `ERR` ;
+4. table/colonne/clé/index géré absent + `auto_initialize_schema=true` -> tenter l'ajout uniquement de la ressource absente, sans supprimer ni modifier les colonnes existantes, puis `ERR` si l'ajout ou la validation complète échoue ;
+5. ignorer les tables et objets non possédés par `ks-store`, quel que soit leur préfixe ;
+6. accepter les extensions additives compatibles, mais refuser une colonne additive étrangère obligatoire sans défaut qui casserait les écritures courantes.
 
-1. si la base est vide, initialiser le nouveau schéma ;
-2. si le nouveau schéma `k_sol_*` est déjà conforme, vérifier puis continuer ;
-3. si des objets historiques `kb_sol_*` sont détectés, refuser l'auto-initialisation avec un diagnostic non destructif demandant une reconstruction explicite ;
-4. ne jamais mélanger silencieusement ancien et nouveau namespace.
+Le contrat de `pre.005` compare les **16 tables, 248 colonnes, 25 clés PK/FK et 79 index physiques** du baseline courant. Le snapshot exhaustif des checks et autres détails frozen reste consolidé en `pre.006`.
 
-Les opérations `DROP`/`TRUNCATE` restent disponibles comme maintenance backend-interne explicite ; elles ne sont pas déclenchées automatiquement par `Store::open()` sur une base non vide.
+Les opérations `DROP`/`TRUNCATE` restent des opérations de maintenance backend-internes explicites et ne sont jamais déclenchées automatiquement sur les ressources étrangères.
 
 ### 15.4 Conséquence sur les tests
 
-Le test de migration `0.5.2 -> 0.5.3` n'est plus requis. Il est remplacé par :
+Le test de migration `0.5.2 -> 0.5.3` n'est pas requis. Il est remplacé par :
 
-- init d'une base vide ;
+- validation du contrat structurel de toutes les tables gérées ;
 - réouverture idempotente d'une base déjà initialisée ;
-- refus propre d'un schéma historique `kb_sol_*` ;
-- reconstruction explicite via les opérations de maintenance retenues ;
-- snapshot exact du schéma final.
+- coexistence non bloquante avec des tables étrangères et des objets historiques `kb_sol_*` ;
+- acceptation des extensions additives compatibles et réparation additive des ressources gérées absentes lorsque l'auto-initialisation est active ;
+- refus des dérives existantes qui nécessiteraient une modification ou suppression pour redevenir compatibles ;
+- snapshot exact du schéma frozen lors de la tranche de gel.
 
-Cette stratégie est acceptable parce que les bases actuelles ne constituent pas encore des contrats de production à préserver.
+Cette stratégie permet aux projections N4 futures d'être additives sans affaiblir le contrat N1/N2/N3 courant.
 
 ## 16. Source de vérité des migrations PostgreSQL
 
@@ -1075,11 +1078,12 @@ La même règle s'applique à tout autre protocole : une table nommée d'après
 
 ### 25.1 Contrat de schéma
 
-- initialisation sur base vide ;
-- réouverture idempotente d'une base déjà initialisée ;
-- refus propre d'une base contenant encore des objets `kb_sol_*` ;
-- absence finale de tables, contraintes, index et séquences `kb_sol_*` après reconstruction ;
 - présence des **16 tables du baseline candidat au gel** retenu en `pre.003` ;
+- validation dans `ks-store` des colonnes requises, types, nullabilités, précisions numériques et défauts nécessaires aux modèles/queries courants ;
+- validation avant toute auto-initialisation des 25 clés PK/FK et des 79 index physiques attendus ; une dérive d'une table existante est bloquante et n'est pas auto-réparée ;
+- acceptation d'une base contenant des tables étrangères ou historiques non gérées, y compris `kb_sol_*` ;
+- acceptation de colonnes additives compatibles et refus d'une colonne additive `NOT NULL` sans défaut qui casserait les écritures courantes ;
+- réouverture idempotente d'une base déjà initialisée ;
 - snapshot exact des colonnes/types/nullabilités/PK/FK/uniques/checks frozen ;
 - présence et contrat séparé des tables top-level/CPI ;
 - test de lecture logique combinée top-level+CPI sans perte, doublon ni ordre instable ;
@@ -1149,8 +1153,8 @@ Avec `KS_SECRET_POSTGRES_TEST_URL` local :
 - transaction rollback ;
 - replay ;
 - diagnostics ;
-- introspection du contrat frozen ;
-- reconstruction propre d'une base de test et refus contrôlé d'un schéma historique `kb_sol_*`.
+- introspection du contrat géré puis du contrat frozen ;
+- vérification que les ressources étrangères/non gérées ne bloquent pas `ks-store` et que toute dérive structurelle d'une ressource gérée est détectée.
 
 ## 26. Snapshot de contrat frozen
 
@@ -1253,20 +1257,22 @@ Le découpage suivant est une **trajectoire fonctionnelle**. Il ne force pas la
 
 ### `0.5.3-pre.005` — finalisation `demo_store`, consommateurs et validation PostgreSQL réelle
 
+La pagination de consultation retenue sépare explicitement deux niveaux : blocs Store fixes de 500 lignes, parcourus par curseurs `Premier/Précédent/Suivant`, puis pagination/tri/filtre DataTables uniquement dans le bloc chargé lorsque la vue utilise DataTables. Chaque chargement ou navigation recalcule le nombre total de lignes/blocs correspondant exactement aux filtres serveur ; aucun champ `offset` ni `limit` éditable n’est exposé pour ces listings. Cette règle couvre Replay Candidates, annotations et journaux matérialisés SPL Token/ATA, sans modifier les limites métier des campagnes, backfills ou RPC.
+
 - supprimer les derniers `Postgres*` de `ks-pipeline-demo-scenarios` ;
 - finaliser les surfaces `demo_store_*` de `kb-app-demo-desktop` autour de résultats tabulaires génériques indépendants du backend ; la nomenclature technique a déjà été migrée en `pre.002` ;
 - refaire `demo_config` afin qu'elle n'expose/interprète plus les champs PostgreSQL/SQLite et consomme uniquement le résumé store sanitisé ;
 - refaire les informations store du splash autour d'une vérification par modèle logique et de compteurs (tables/index attendus, présents, créés), sans afficher les noms physiques ;
 - confirmer que `ks-pipeline` reste inchangé dans son rôle d'orchestration ;
-- tests base vide + réouverture + refus ancien schéma ;
-- validations PostgreSQL réelles ;
+- validation de compatibilité structurelle des ressources gérées + réouverture, avec coexistence non bloquante des ressources étrangères/historiques ;
+- validations PostgreSQL réelles depuis `ks-store`, les consommateurs ne réimplémentant aucune introspection ;
 - lancer Tauri parce que les diagnostics/surfaces desktop auront changé.
 
 ### `0.5.3-pre.006` — gel de contrat et réconciliation technique
 
 - produire le snapshot machine-readable frozen avec le nombre réel de tables N1/N2/N3 après canari future-decoder, sans imposer artificiellement la baseline de 13 ;
 - canari exact du schéma logique ;
-- audit workspace anti-`kb_sol_` actif ;
+- audit workspace vérifiant qu’aucune ressource/requête active de `ks-store` n’utilise `kb_sol_*`, sans interdire leur coexistence physique ;
 - audit anti-PostgreSQL hors `ks-store` ;
 - audit secrets/logging ;
 - confirmer qu'aucune table trading/DEX ni projection metadata N4 non auditée n'a été introduite ;
@@ -1319,7 +1325,7 @@ cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
 
 La version ne peut être clôturée que si :
 
-- il n'existe plus d'objet actif `kb_sol_*` ;
+- aucune ressource gérée ni requête active de `ks-store` n’utilise `kb_sol_*` ; leur coexistence comme objets non gérés reste tolérée ;
 - les 16 tables du baseline candidat retenu en `pre.003` correspondent exactement au snapshot frozen documenté ;
 - `block_time` est conservé lorsqu'il existe et reste `NULL` sinon ;
 - les top-level et CPI restent physiquement séparées mais peuvent être sélectionnées séparément ou comme flux logique commun pour le decode ;
@@ -1551,21 +1557,21 @@ La nouvelle arborescence contient :
 migrations/postgres/
   schema/tables/       16
   schema/constraints/ 129
-  schema/indexes/      59
+  schema/indexes/      63
   maintenance/truncate/16
   maintenance/drop/    16
 ```
 
-Soit **236 ressources SQL**. Chaque ressource contient une seule instruction top-level et est embarquée une seule fois par `include_str!`.
+Soit **240 ressources SQL**. Chaque ressource contient une seule instruction top-level et est embarquée une seule fois par `include_str!`.
 
 L'orchestrateur PostgreSQL global :
 
 - valide les ressources ;
-- refuse les objets historiques `kb_sol_*` ;
-- ouvre une transaction ;
-- prend un advisory lock ;
-- applique tables, contraintes et index dans l'ordre ;
-- commit uniquement lorsque le baseline complet est cohérent.
+- inspecte d'abord les tables gérées déjà présentes et refuse toute dérive de colonnes, PK/FK ou index ;
+- ignore les objets étrangers ou historiques non gérés, y compris `kb_sol_*` ;
+- si aucune table gérée ne manque, n'exécute aucune initialisation ;
+- si des tables gérées manquent et que l'auto-initialisation est autorisée, ouvre une transaction, prend un advisory lock et applique uniquement les tables manquantes, leurs contraintes puis leurs index ;
+- commit la création puis revalide le baseline complet.
 
 Les initialiseurs partiels raw/Core/decode sont supprimés, y compris des tests. Une initialisation ne peut donc plus valider accidentellement un sous-schéma comme si le baseline complet était prêt.
 
@@ -1582,7 +1588,7 @@ Le résumé backend-agnostique expose :
 
 sans publier les noms physiques.
 
-Le backend PostgreSQL attend actuellement **75 index** : 59 index explicites et les 16 index de clés primaires produits par PostgreSQL.
+Le backend PostgreSQL attend actuellement **79 index** : 63 index explicites et les 16 index de clés primaires produits par PostgreSQL.
 
 ### 33.8 Conclusion du canari future-decoder
 
@@ -1609,7 +1615,6 @@ Les autres metadata transactionnelles auditées (`fee`, rewards, compute units,
 - les projections N4 metadata/trading.
 
 Ces points restent dans les tranches suivantes et peuvent décaler le premier candidat de clôture au-delà de `pre.007`.
-
 ## 34. État réalisé de `0.5.3-pre.004`
 
 `pre.004` ferme la tranche repositories/replay sans ajouter de table et sans déclarer encore le gel formel N1/N2/N3.