v0.5.3-pre.003

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: 7 -->
+<!-- version: 8 -->
 
 # Plan `0.5.3` — audit et normalisation de `ks-store`
 
@@ -174,7 +174,7 @@ Les fonctions privées PostgreSQL correspondantes sont séparées et utilisent `
 | `k_sol_decode_events`                | `DecodeObservationInsert`                                                        | `DecodePipelineStore`                         | `decode_pipeline_queries`                                            | `ks-pipeline::decode_replay`                                 |
 | `k_sol_decode_coverage_declarations` | `DecodeCoverageDeclarationInsert`                                                | `DecodePipelineStore`                         | `decode_pipeline_queries`                                            | `ks-pipeline::decode_replay`                                 |
 | `k_sol_decode_coverage_observations` | `DecodeCoverageObservationInsert`, `DecodeCoverageSummaryRow`                    | `DecodePipelineStore`                         | `decode_pipeline_queries`                                            | pipeline + desktop diagnostics                               |
-| `k_sol_mat_outputs`                  | `MaterializedOutputInsert`, `MaterializedEventQueryRow`                          | `DecodePipelineStore`                         | `decode_pipeline_queries`                                            | pipeline, scénarios Devnet, desktop                          |
+| `k_sol_mat_outputs`                  | `MaterializedOutputInsert`, `MaterializedOutputQueryRow`                         | `DecodePipelineStore`                         | `decode_pipeline_queries`                                            | pipeline, scénarios Devnet, desktop                          |
 
 ### 5.1 Contrats publics hérités sans implémentation
 
@@ -1079,7 +1079,7 @@ La même règle s'applique à tout autre protocole : une table nommée d'après
 - 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 **13 tables de baseline**, plus des éventuels contrats N1/N2/N3 génériques explicitement retenus après le canari future-decoder ;
+- présence des **16 tables du baseline candidat au gel** retenu en `pre.003` ;
 - 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 ;
@@ -1154,7 +1154,7 @@ Avec `KS_SECRET_POSTGRES_TEST_URL` local :
 
 ## 26. Snapshot de contrat frozen
 
-Le snapshot `0.5.3` couvre les **13 tables existantes de baseline, plus toute structure N1/N2/N3 générique dont le canari future-decoder démontre la nécessité avant gel**, ainsi que les tables transverses de processing/decode qui assurent leur idempotence et leur journalisation. Les futures projections N4 disposent de contrats/version propres, mais ne sont pas ajoutées à ce snapshot frozen fondamental.
+Le snapshot `0.5.3` couvre les **16 tables du baseline candidat au gel retenu en `pre.003`**, y compris les trois contrats génériques ajoutés par le canari future-decoder (`account observation`, `account state`, `transaction return data`), ainsi que les tables transverses de processing/decode qui assurent leur idempotence et leur journalisation. Les futures projections N4 disposent de contrats/version propres, mais ne sont pas ajoutées à ce snapshot frozen fondamental.
 
 Une fixture machine-readable sera créée avant clôture, par exemple :
 
@@ -1320,7 +1320,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_*` ;
-- les 13 tables de baseline et toute table N1/N2/N3 générique ajoutée après le canari future-decoder correspondent exactement au snapshot frozen documenté ;
+- 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 ;
 - replay et invalidation descendante sont cohérents et transactionnels, avec contrats N1 -> N2, N2 -> N3 et frontière N3 -> N4 documentée/testable ;
@@ -1453,3 +1453,159 @@ Le nettoyage fin de l’instrumentation des requêtes (durées, nombres de ligne
 - n’implémente pas Anchor.
 
 Ces travaux restent affectés aux tranches `pre.003+` prévues par le présent plan.
+
+## 33. État réalisé de `0.5.3-pre.003`
+
+`pre.003` réalise la reconstruction physique PostgreSQL et ferme les principaux manques révélés par le canari future-decoder. Le résultat est un **baseline candidat au gel**, pas encore le snapshot frozen final de `pre.006`.
+
+### 33.1 Baseline candidat : 16 tables
+
+Les 13 tables historiques sont conservées conceptuellement sous le namespace `k_sol_*`, sans fusion des instructions top-level/CPI. Trois contrats Solana génériques sont ajoutés avant gel :
+
+1. `k_sol_obs_account_observations` — observation N1 d'un état de compte avec bytes exacts, hash et provenance d'acquisition ;
+2. `k_sol_core_account_states` — état N2 canonique dérivé d'une observation de compte ;
+3. `k_sol_core_return_data` — conservation N2 de la `returnData` transactionnelle déjà présente dans le document canonique N1.
+
+Le baseline candidat comporte donc :
+
+```text
+N1
+  k_sol_raw_transactions
+  k_sol_obs_transaction_observations
+  k_sol_obs_account_observations
+
+N2
+  k_sol_core_transactions
+  k_sol_core_account_keys
+  k_sol_core_instructions
+  k_sol_core_inner_instructions
+  k_sol_core_logs
+  k_sol_core_balance_changes
+  k_sol_core_return_data
+  k_sol_core_account_states
+
+N3 / transverse
+  k_sol_ops_processing_ledger
+  k_sol_decode_events
+  k_sol_decode_coverage_declarations
+  k_sol_decode_coverage_observations
+  k_sol_mat_outputs
+```
+
+Aucune structure n'est nommée d'après Anchor, une IDL, un DEX ou un protocole.
+
+### 33.2 Temporalité et Core instructionnel
+
+`block_time` devient une colonne nullable de premier rang sur `k_sol_raw_transactions` et `k_sol_core_transactions`. La Core extraction vérifie la cohérence entre le document canonique N1 et l'ancre Core lorsqu'ils sont reliés.
+
+Les instructions top-level et CPI restent physiquement séparées. Les deux contrats portent désormais `stack_height` lorsque Solana la fournit. La Core extraction reconstruit les chemins CPI imbriqués à partir de la pile ; `parent_instruction_path` pointe alors vers le parent immédiat. Lorsque `stackHeight` est absent, la CPI reste rattachée de manière déterministe à la top-level racine sans inventer un niveau de pile.
+
+Les CPI reçoivent dans le schéma les mêmes champs de lifecycle/processor que les top-level. La sélection autonome et le replay opérationnel CPI restent à finaliser dans `pre.004`.
+
+### 33.3 Replay Core v3
+
+`MdCoreInstructionReplayInput` passe à la version 3 et peut transporter :
+
+- `block_time` ;
+- `stack_height` ;
+- `parent_instruction_path` ;
+- le contexte ordonné des instructions top-level ;
+- la `returnData` transactionnelle.
+
+Le champ de contexte nouveau est nommé `top_level_instructions_json`. Les usages historiques du terme `outer` dans des décodeurs existants ne sont pas renommés mécaniquement lorsqu'ils décrivent encore une sémantique propre à ces contrats.
+
+Le constructeur historique reste disponible pour les tests et sources synthétiques ; les inputs provenant du Core persistant sont enrichis par le store.
+
+### 33.4 Provenance de schéma N3
+
+`k_sol_decode_events` réserve des champs nullable de provenance de schéma :
+
+```text
+schema_kind
+schema_id
+schema_version
+schema_hash
+```
+
+Ils restent vides pour les décodeurs compilés actuels. Un futur mécanisme basé sur un schéma externe/IDL pourra les renseigner sans introduire de colonne Anchor ou modifier N1/N2.
+
+### 33.5 `k_sol_mat_outputs`
+
+Le renommage conceptuel est réalisé jusque dans l'API :
+
+```text
+MaterializedOutputFilter
+MaterializedOutputQueryRow
+DecodePipelineStore::list_materialized_outputs
+```
+
+`k_sol_mat_outputs` reste le journal N3 générique versionné et la source de replay vers les futures projections N4.
+
+### 33.6 Ressources PostgreSQL atomiques
+
+La chaîne active historique `0001` à `0004` est retirée. Les scripts de maintenance monolithiques sont également retirés.
+
+La nouvelle arborescence contient :
+
+```text
+migrations/postgres/
+  schema/tables/       16
+  schema/constraints/ 129
+  schema/indexes/      59
+  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!`.
+
+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.
+
+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.
+
+### 33.7 Diagnostics du schéma
+
+Le diagnostic ne dépend plus de `_sqlx_migrations` pour déterminer si le baseline courant est disponible. Il compare les ressources connues réellement présentes.
+
+Le résumé backend-agnostique expose :
+
+- modèles logiques ;
+- compte de tables ;
+- compte d'index ;
+- état ready/partial/not-initialized ;
+
+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.
+
+### 33.8 Conclusion du canari future-decoder
+
+Le canari a effectivement révélé deux pertes/absences structurelles de la baseline `0.5.2` :
+
+- `returnData` était conservée en N1 mais perdue en N2 ;
+- aucun chemin persistant générique d'observation/état de compte n'était réservé.
+
+Ces deux lacunes sont corrigées avant gel.
+
+Les autres metadata transactionnelles auditées (`fee`, rewards, compute units, cost units) restent conservées dans le document canonique N1. Elles ne sont pas nécessaires au décodage futur et ne justifient pas de gonfler l'ancre N2 avant gel ; une projection additive reste possible si un besoin queryable stable apparaît.
+
+### 33.9 Travaux volontairement laissés à `pre.004+`
+
+`pre.003` ne clôt pas encore :
+
+- la lecture logique commune top-level+CPI et le replay CPI autonome ;
+- l'ingestion/replay opérationnel du nouveau flux account observation -> account state ;
+- l'invalidation descendante N1 -> N2 -> N3 -> N4 ;
+- la pagination cursorisée ;
+- la validation des index par plans réels sur dataset représentatif ;
+- le snapshot machine-readable frozen ;
+- la refonte fonctionnelle desktop finale ;
+- 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`.