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.

5.2 KiB Raw Blame History