# ks-store `ks-store` porte la frontière de persistance généraliste de Khadhroony Solana. Les consommateurs utilisent des contrats fonctionnels et une façade `Store` indépendante du moteur concret ; PostgreSQL reste l'implémentation opérationnelle de `0.5.3`, confinée à l'intérieur de la crate. ## Périmètre La crate expose : - `Store` et `StoreOpenOptions` comme façade d'ouverture et handle persistant backend-agnostique ; - 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 ; - des transactions atomiques pour extraction, décodage et matérialisation. ## Frontière backend `PostgresStore`, `PostgresStoreOptions`, `sqlx::PgPool`, les requêtes SQL et les noms physiques de tables sont privés à `ks-store`. `ks-pipeline`, les scénarios et les applications ne doivent connaître que `Store`, les repositories et les DTO fonctionnels. `ks-store` ne dépend pas de `ks-config`. Un consommateur lui fournit un backend sélectionné et un objet `backend_options` opaque ; seul `ks-store` interprète et valide les paramètres PostgreSQL puis crée la connexion. ## Configuration et sécurité `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. ## Baseline PostgreSQL `0.5.3-pre.003` `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 - garantir les invariants des données persistées ; - posséder la connexion et l'initialisation du backend actif ; - fournir des frontières async typées au pipeline ; - protéger les opérations multi-tables par transactions ; - borner les diagnostics et replay exposés ; - permettre le remplacement futur de PostgreSQL sans réécriture des consommateurs. ## Hors périmètre 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 - dépend de `ks-core` pour les erreurs ; - utilise les contrats de replay de `ks-lib` ; - est consommée principalement par `ks-pipeline`, `ks-pipeline-demo-scenarios` et `kb-app-demo-desktop` ; - ne dépend pas de `ks-config`. ## Documents - [Utilisation](USAGE.md) - [Travaux restants](TODO.md) - [Historique](CHANGELOG.md) - [Architecture du stockage](../docs/architecture/STORAGE_ARCHITECTURE.md) - [Plan actif `0.5.3`](../docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md)