Architecture du stockage

1. Responsabilité de `ks-store`

ks-store réunit :

la façade publique backend-agnostique Store et ses options d'ouverture ;
les contrats store-neutral ;
les DTO et entités persistées ;
la pagination, le replay et les rapports de santé ;
les traits de repositories ;
les résumés runtime/init sanitisés ;
l’implémentation PostgreSQL privée ;
les migrations et requêtes appartenant au backend actif.

Depuis 0.5.3-pre.002, les consommateurs ne construisent plus un backend concret. ks-store possède la connexion et le dispatch interne ; PostgresStore, PgPool et SQLx ne traversent plus sa frontière publique.

2. Frontières

2.1 Contrats store-neutral

Les contrats ne dépendent pas des détails SQL lorsqu’une abstraction stable est suffisante. Ils décrivent les entrées, sorties, identifiants, pages, diagnostics et erreurs nécessaires aux consommateurs. StoreOpenOptions transporte un code backend et un objet d'options opaque ; seul ks-store interprète le moteur sélectionné.

Le résumé runtime expose des modèles logiques et des compteurs d'objets par catégorie sans publier les noms physiques. PostgreSQL peut ainsi exposer des compteurs table/index, tandis qu'un futur backend peut utiliser d'autres catégories sans modifier le desktop.

2.2 Adaptateur PostgreSQL

Le module PostgreSQL possède :

la validation de ses options ;
la connexion et l’initialisation ;
l’application idempotente des migrations ;
les requêtes typées ;
les diagnostics physiques ;
les opérations de replay et de sélection de candidats ;
le target de tracing canonique ks-store, enrichi des champs backend="postgres", domain="ks-store.pg" et action pour les opérations PostgreSQL.

Les détails physiques restent privés. Les erreurs et résumés traversant la façade ne doivent pas divulguer de DSN, password ou option sensible.

2.3 Modèles partagés

Les modèles métier communs restent dans ks-lib lorsqu’ils dépassent la seule persistance. ks-store ne doit pas créer une seconde définition concurrente d’un contrat partagé.

3. Catégories de données

Le stockage distingue quatre niveaux durables :

N1 — acquisition et raw canonique ;
N2 — Core Solana canonique ;
N3 — decode/materialization générique et journaux versionnés ;
N4 — projections spécialisées/queryables additives.

N1/N2/N3 constituent la fondation fortement gelée après 0.5.3, sous réserve d'une urgence ou d'une omission structurelle majeure. N4 reste plus évolutif. Les replays N1 -> N2, N2 -> N3 et N3 -> N4 doivent pouvoir être exécutés indépendamment et de manière idempotente.

Les noms de tables, contrats de replay et APIs publiques sont documentés dans ks-store/USAGE.md à partir des exports et migrations actuels.

4. Propriétés attendues

initialisation idempotente ;
pagination bornée ;
traçabilité des campagnes ;
absence de double effet lors des replays ;
validation stricte des entrées ;
erreurs explicites ;
séparation entre données brutes, résultats de décodage et matérialisations.

La série 0.5.3 normalisera cette fondation avant l’arrivée des protocoles trading. Elle doit notamment distinguer slot, block_time et les timestamps d’acquisition/persistance, normaliser la structure interne de ks-store, vérifier les champs et index manquants et préparer les futures matérialisations trading, routing et multi-pools sans perdre les contrats de provenance et d’idempotence.

La même migration remplace le préfixe historique des tables Solana kb_sol_* par k_sol_*. La base peut encore être reconstruite ou migrée proprement avant 0.6.x, il n’est donc pas nécessaire de conserver indéfiniment l’ancien préfixe. Le préfixe kb_* est réservé aux éventuelles tables dont la responsabilité appartient réellement au domaine applicatif Bot, pas aux faits Solana simplement consommés par le bot.

5. Données de test

Les fixtures privées, bases locales et preuves temporaires ne font pas partie des livraisons. Les matrices contractuelles partagées restent sous test-fixtures/contract-matrices/ lorsqu’elles sont nécessaires aux tests.

4.3 KiB Raw Blame History Unescape Escape