v0.5.3-pre.003

ks-store/README.md

@@ -1,5 +1,5 @@
 <!-- file: ks-store/README.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # ks-store
 
@@ -10,7 +10,7 @@
 La crate expose :
 
 - `Store` et `StoreOpenOptions` comme façade d'ouverture et handle persistant backend-agnostique ;
-- les DTO et entités raw, observations, Core, décodage, matérialisation et ledger ;
+- les DTO et entités N1 raw/acquisition, N2 Core, N3 decode/materialization et ledger ;
 - les traits async `StoreHealthStore`, `RawTransactionStore`, `CoreTransactionStore`, `CoreExtractionStore` et `DecodePipelineStore` ;
 - les filtres et résultats de replay sans préfixe backend ;
 - des diagnostics et résumés runtime/init sanitisés ne révélant ni secret ni nom physique d'objet ;
@@ -26,11 +26,35 @@ La crate expose :
 
 `StoreOpenOptions` ne dérive pas `Debug` et ne rend pas les options backend accessibles après construction. Les résumés publics exposent uniquement des informations explicitement sanitisées : code backend, présence d'une connexion, état d'initialisation, health, modèle logique et compteurs.
 
-Le backend PostgreSQL masque le descripteur de connexion et utilise l’unique target de crate `ks-store`, complété par `backend="postgres"`, `domain="ks-store.pg"` et un champ `action` structuré. Aucun DSN, password ou valeur bindée n'est destiné aux diagnostics publics.
+Le backend PostgreSQL masque le descripteur de connexion et utilise l'unique target de crate `ks-store`, complété par `backend="postgres"`, `domain="ks-store.pg"` et un champ `action` structuré. Aucun DSN, password ou valeur bindée n'est destiné aux diagnostics publics.
 
-## Schéma pendant `0.5.3`
+## Baseline PostgreSQL `0.5.3-pre.003`
 
-`0.5.3-pre.002` ne modifie pas encore les tables héritées `kb_sol_*`. Leur reconstruction sous `k_sol_*`, les ressources SQL atomiques et le gel N1/N2/N3 commencent en `pre.003` conformément au plan actif.
+`pre.003` reconstruit directement le schéma actif sous le namespace `k_sol_*`. Les quatre migrations historiques `0001` à `0004` et les deux scripts de maintenance monolithiques ne font plus partie de la chaîne active.
+
+Le baseline candidat au gel comprend **16 tables N1-N3** :
+
+- N1 : transactions raw, observations d'acquisition de transactions et observations génériques de comptes ;
+- N2 : transaction Core, clés de comptes, instructions top-level, CPI, logs, variations de balances, return data et états canoniques de comptes ;
+- N3/transverse : processing ledger, événements décodés, déclarations/observations de couverture et `k_sol_mat_outputs`.
+
+Les ressources PostgreSQL sont rangées sous `migrations/postgres/` et suivent la règle **une instruction SQL par fichier**. L'orchestrateur privé applique tables, contraintes et index dans une transaction unique et refuse explicitement un schéma historique contenant encore des objets `kb_sol_*`.
+
+Le baseline comporte actuellement **236 ressources SQL atomiques** et **75 index attendus**, comptés sans exposer leurs noms dans l'API publique.
+
+## Readiness des futurs décodeurs
+
+Le canari future-decoder a conduit à trois corrections génériques avant gel :
+
+- `block_time` devient une colonne de premier rang sur raw/Core transaction ;
+- `returnData` est conservée explicitement dans le Core via `k_sol_core_return_data` ;
+- un chemin générique d'observation/état de compte est réservé via `k_sol_obs_account_observations` et `k_sol_core_account_states`.
+
+Les instructions top-level et CPI restent physiquement séparées. Les deux contrats portent `stack_height` lorsque disponible ; les CPI conservent un `parent_instruction_path` vers le parent immédiat reconstructible.
+
+N3 réserve en outre une provenance de schéma nullable sur les observations décodées afin qu'un futur décodeur basé sur un schéma externe/IDL puisse tracer ce schéma sans remodeler le Core.
+
+Aucune structure `anchor_*`, DEX ou projection metadata N4 n'est créée en `pre.003`.
 
 ## Responsabilités
 
@@ -43,7 +67,7 @@ Le backend PostgreSQL masque le descripteur de connexion et utilise l’unique t
 
 ## Hors périmètre
 
-La crate ne décode pas les instructions, n'acquiert pas les transactions et ne décide pas quelle matérialisation ou projection N4 exécuter. Elle persiste les faits produits par `ks-lib` et orchestrés par `ks-pipeline`.
+La crate ne décode pas les instructions, n'acquiert pas elle-même les transactions/comptes et ne décide pas quelle matérialisation ou projection N4 exécuter. Elle persiste les faits produits par `ks-lib` et orchestrés par `ks-pipeline`.
 
 ## Relations