v0.5.3-pre.003

docs/guides/POSTGRES_STORAGE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/guides/POSTGRES_STORAGE.md -->
-<!-- version: 5 -->
+<!-- version: 6 -->
 
 # Guide PostgreSQL et contrats de stockage
 
@@ -35,47 +35,114 @@ Le descripteur public éventuellement affiché provient du résumé runtime et e
 
 ## Domaines
 
-- raw : acquisitions et observations ;
-- Core : transactions, instructions, comptes et contexte normalisés ;
-- decode : ledger, observations décodées et matérialisations ;
-- replay : candidats et résumés bornés.
+- N1 raw/acquisition : transactions canoniques, observations de transactions et observations génériques de comptes ;
+- N2 Core : transactions, clés, top-level, CPI, logs, variations de balances, return data et états de comptes ;
+- N3/transverse : ledger, observations décodées, couverture et `k_sol_mat_outputs` ;
+- replay/diagnostic : sélections et résumés bornés au-dessus de ces contrats.
 
-## Migrations
+## Baseline `0.5.3-pre.003`
 
-`0.5.3-pre.002` conserve temporairement le schéma PostgreSQL historique `kb_sol_*` et son mécanisme d'initialisation afin de réaliser d'abord la rupture d'API backend. `pre.003` reconstruit le baseline sous `k_sol_*`, range les ressources sous `ks-store/migrations/postgres/` et impose une instruction SQL par fichier exécutée par les fonctions privées du backend.
+`pre.003` reconstruit directement le schéma sous `k_sol_*`. Les bases Devnet/Mainnet/test historiques sont considérées reconstructibles ; aucune migration in-place depuis `kb_sol_*` n'est fournie.
 
-Les bases Devnet/Mainnet/test `0.5.2` sont reconstructibles : aucune compatibilité in-place n'est requise pour ce changement de baseline.
+Le comportement attendu à l'ouverture est :
+
+1. base vide + auto-init : création du baseline complet ;
+2. base `k_sol_*` déjà conforme : vérification/idempotence ;
+3. base contenant encore des objets `kb_sol_*` : refus non destructif et demande de reconstruction explicite ;
+4. `DROP`/`TRUNCATE` : opérations de maintenance distinctes, jamais déclenchées implicitement par `Store::open()`.
+
+Le baseline candidat au gel comprend 16 tables N1-N3.
+
+## Ressources SQL
+
+Les ressources actives sont sous :
+
+```text
+ks-store/migrations/postgres/
+  schema/
+    tables/
+    constraints/
+    indexes/
+  maintenance/
+    truncate/
+    drop/
+```
+
+Chaque fichier contient une instruction SQL. Le code PostgreSQL privé utilise `include_str!` et l'orchestrateur global exécute le schéma dans une transaction unique avec advisory lock.
+
+Il n'existe plus trois initialiseurs raw/Core/decode indépendants : **l'initialisation du schéma est globale**.
+
+Le corpus `pre.003` contient actuellement :
+
+- 16 créations de tables ;
+- 129 ressources de contraintes ;
+- 59 créations d'index explicites ;
+- 16 ressources `TRUNCATE` ;
+- 16 ressources `DROP` ;
+- soit **236 ressources SQL**.
+
+PostgreSQL attend **75 index** au total dans son diagnostic : 59 index explicites plus les 16 index de clé primaire créés par PostgreSQL.
+
+Les index non uniques restent des optimisations physiques et ne font pas partie du gel logique N1-N3.
+
+## Statut du schéma
+
+La façade n'utilise plus `_sqlx_migrations` comme preuve du baseline actuel. Le statut est dérivé du contrat réellement observé :
+
+- aucune ressource connue : non initialisé ;
+- toutes les ressources attendues : contrat courant ;
+- présence partielle : drift/partial.
+
+Le résumé d'initialisation expose des compteurs de modèles, tables et index sans publier leurs noms physiques.
 
 ## Compatibilité des identités de processeurs
 
-Depuis `0.5.1-pre.003`, les identités techniques produites par `ks-lib` utilisent `ks-lib-decoder.*`, `ks-lib-executor.*` et `ks-lib-materializer.*`. Une base alimentée avant cette migration peut encore contenir des valeurs `kb-lib.*` dans les contrats de provenance/replay.
+Depuis `0.5.1-pre.003`, les identités techniques produites par `ks-lib` utilisent `ks-lib-decoder.*`, `ks-lib-executor.*` et `ks-lib-materializer.*`.
 
-Aucune migration SQL automatique de ces valeurs n'est ajoutée en `0.5.1` : avant `0.6.x`, une base conservée doit soit être reconstruite proprement, soit faire l'objet d'une migration de données explicitement contrôlée avant reprise du replay. Il ne faut pas exploiter durablement un même corpus avec les anciennes et nouvelles identités mélangées. Les noms de tables `kb_sol_*` restent inchangés jusqu'au chantier `0.5.3`.
+Comme les bases `0.5.2` doivent être reconstruites pour le nouveau baseline `0.5.3`, les anciennes identités `kb-lib.*` ne sont pas migrées automatiquement dans ce chantier.
+
+## Core readiness
+
+`pre.003` ajoute les éléments génériques nécessaires au futur redécodage :
+
+- `block_time` sur raw/Core transaction ;
+- `stack_height` sur top-level/CPI ;
+- parent CPI immédiat reconstructible ;
+- `k_sol_core_return_data` ;
+- `k_sol_obs_account_observations` ;
+- `k_sol_core_account_states` ;
+- provenance de schéma optionnelle sur les observations décodées.
+
+Ces contrats sont indépendants d'Anchor/IDL. Aucun parser Anchor ni table `anchor_*` n'appartient à `0.5.3`.
 
 ## Repositories
 
-Les traits publics et la façade `Store` décrivent des opérations fonctionnelles indépendantes du moteur. PostgreSQL implémente ces contrats à l’intérieur de `ks-store`; aucune crate consommatrice ne reçoit `PgPool`, un type SQLx ou une requête concrète. Les opérations de lecture utilisent des filtres et paginations bornés.
+Les traits publics et la façade `Store` décrivent des opérations fonctionnelles indépendantes du moteur. PostgreSQL implémente ces contrats à l'intérieur de `ks-store`; aucune crate consommatrice ne reçoit `PgPool`, un type SQLx ou une requête concrète.
+
+Le schéma des observations/états de comptes est introduit avant gel en `pre.003`; son ingestion/replay fonctionnel est raccordé dans la tranche repositories/replay suivante.
 
 ## Diagnostics
 
 La surface publique expose :
 
 - health snapshot ;
-- migration snapshot ;
+- schema/migration snapshot générique ;
 - backend descriptor masqué ;
 - résumé de configuration sanitisé ;
 - résumé d'initialisation/vérification par modèle logique ;
-- diagnostics de ressources raw/Core/decode/materialization sans nom physique d'objet.
+- diagnostics de ressources sans nom physique d'objet.
 
-Les noms de tables, index, contraintes et le SQL restent des détails backend-internes. Les traces PostgreSQL utilisent l’unique `target: crate::TRACING_TARGET` (`ks-store`) avec les champs structurés `backend="postgres"`, `domain="ks-store.pg"` et un `action` précis (`connection`, `migration`, `query`, `health`, `replay`, etc.).
+Les noms de tables, index, contraintes et le SQL restent des détails backend-internes. Les traces PostgreSQL utilisent l'unique `target: crate::TRACING_TARGET` (`ks-store`) avec les champs structurés `backend="postgres"`, `domain="ks-store.pg"` et un `action` précis.
 
 ## Invariants
 
 - aucune donnée canonique ne doit être dupliquée sans justification ;
 - les écritures rejouables doivent être idempotentes ;
 - la progression de campagne doit rester cohérente avec les lignes effectivement traitées ;
-- les requêtes dynamiques n’acceptent que des identifiants validés ;
-- les détails PostgreSQL utiles au diagnostic restent backend-internes ; les erreurs traversant la façade publique ne doivent jamais divulguer DSN, password ou options sensibles.
+- les requêtes dynamiques n'acceptent que des identifiants validés ;
+- les détails PostgreSQL utiles au diagnostic restent backend-internes ;
+- les erreurs traversant la façade publique ne doivent jamais divulguer DSN, password ou options sensibles ;
+- un nouveau décodeur doit pouvoir exploiter N1/N2/N3 sans remodelage normal de ces niveaux.
 
 ## Références