khadhroony-bot3/ks-store/CHANGELOG.md

<!-- file: ks-store/CHANGELOG.md -->
<!-- version: 19 -->

# CHANGELOG — ks-store

## `0.5.3-pre.001`

### Audit / plan

- inventorie les 13 tables actives de `0.5.2`, leurs migrations, DTO, repositories, requêtes et consommateurs ;
- conserve les 13 tables existantes comme baseline avec instructions top-level et CPI physiquement séparées, mais rendues symétriques pour lifecycle/replay et accessibles via une lecture logique commune ; le nombre final N1/N2/N3 peut augmenter si le canari future-decoder révèle un manque Solana générique avant gel ;
- classe `block_time` comme correction pré-gel de `raw_transactions` et `core_transactions`, sans duplication dans chaque projection fille ;
- conserve impérativement le journal générique N3 de matérialisation sous la cible `k_sol_mat_outputs` et réserve les projections spécialisées au niveau N4 ;
- formalise le gel fort N1 raw/N2 Core/N3 materialization après `0.5.3`, la souplesse contrôlée des projections N4 et les replays N1 -> N2, N2 -> N3 et N3 -> N4 ;
- retient pour les metadata deux projections N4 futures : asset/token metadata commune Metaplex + Token-2022 et program metadata distincte pour SPM ;
- normalise le vocabulaire d'instruction vers `top-level`, conserve les CPI séparées et exige `stack_height`/parent CPI immédiat lorsque reconstructible ;
- ajoute un canari de gel future-decoder/Anchor-readiness : N1/N2/N3 doivent conserver les données Solana génériques nécessaires aux instructions/CPI, événements/logs, `returnData`, états/observations de comptes et provenance de schéma, sans ajouter de contrat `anchor_*` ; les 13 tables existantes restent une baseline et non un quota final si un manque générique est découvert avant gel ;
- formalise la reconstruction `kb_sol_* -> k_sol_*`, l'arborescence `migrations/postgres/`, une instruction SQL par fichier exécutée via `include_str!`, l'audit des index/paginations/BIGINT et les règles de replay/invalidation ;
- définit la façade de stockage backend-agnostique, l'encapsulation de PostgreSQL, la stratégie de configuration backend opaque jusqu'à `ks-store`, le résumé runtime/init sans secrets, la future réutilisation d'un `Store` persistant dans `AppState`, la refonte backend-agnostique de `demo_sql`/`demo_config`/splash et les targets `ks-store.pg.*` ;
- ajoute [`docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md`](../docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md) ;
- ne crée aucune table DEX/trading ni projection metadata N4 dans `0.5.3` ;
- considère `pre.007` comme premier candidat de clôture et autorise explicitement son décalage si des manques apparaissent ;
- ne modifie aucune table, migration SQL, requête ou API Rust de production dans cette prerelease de plan.

## `0.5.1-pre.004`

- migre la variable des tests PostgreSQL optionnels vers `KS_SECRET_POSTGRES_TEST_URL` ;
- renomme le helper SQL de rollback réservé aux tests de `kb_test_reject_decode_ledger` vers `ks_test_reject_decode_ledger` ;
- ne modifie aucune migration, table, requête SQL ou identité persistée.

## `0.5.1-pre.003`

- aligne le contrat de test de persistance/replay sur l'identité de décodeur `ks-lib-decoder.*` ;
- documente qu'une base contenant encore des identités `kb-lib.*` doit être reconstruite ou migrée explicitement avant reprise durable du replay ;
- ne modifie ni les migrations SQL `0001` à `0004`, ni les tables `kb_sol_*`, dont le renommage reste réservé à `0.5.3`.

## `0.5.1-pre.002`

- renomme `kb-store` en `ks-store` et `kb_store` en `ks_store` ;
- aligne le target racine et les consommateurs, tout en conservant volontairement les tables `kb_sol_*` et les migrations SQL inchangées jusqu'à `0.5.3`.

## `0.5.0-pre.003`

### Documentation

- documente l’audit préparatoire `0.5.3` sans modifier le schéma ni les migrations `0001` à `0004` ;
- formalise dans le TODO la caractérisation du schéma `0.4.8`, la séparation de `block_time` on-chain des temps d’acquisition/persistance, l’enveloppe de faits/provenance et la décision future sur les projections normalisées parallèles au journal générique de matérialisation.

## 0.4.6

- alignement de la crate sur la version fonctionnelle bot3 `0.4.6` ;
- clôture des tâches de migration applicables et report explicite des évolutions ultérieures dans le TODO.

## 0.1.0-pre.074

- clôture de la tâche documentaire préalable à `0.4.6` après publication du guide PostgreSQL et stockage ;

## 0.1.0-pre.073

- ajout du guide transversal [`docs/guides/POSTGRES_STORAGE.md`](../docs/guides/POSTGRES_STORAGE.md) ;

## 0.1.0-pre.072

- reclassement du TODO selon les blocants avant `0.4.6`, les travaux `0.4.7`, les versions ultérieures et les dépendances conditionnelles.

## 0.1.0-pre.070

- enrichissement de `USAGE.md` avec plusieurs exemples couvrant les familles d’API publiques significatives.

## 0.1.0-pre.069

### Documentation

- création de `TODO.md`, `USAGE.md` et du changelog détaillé ;
- réécriture du README autour des contrats consolidés et de `PostgresStore` ;
- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
- retrait des constats sans action du TODO et des travaux futurs du changelog ;
- réécriture de `TODO.md` sous forme de tâches uniquement ;
- correction des exemples de `USAGE.md` afin de ne pas utiliser l’opérateur `?`.

## 0.1.0

### Migré

- consolidation de `ks_store_core`, `ks_store_pg` et des contrats associés dans `ks-store` ;
- migration des tables raw, observations, Core, ledger, événements décodés, couverture et matérialisations ;
- migration des migrations SQL, diagnostics et requêtes de replay.

### Modifié

- adoption de Rust 2024 et des règles Khadhroony ;
- maintien des modules internes privés derrière une façade publique contrôlée ;
- erreurs structurées via `ks_core::Error` et transactions async via `sqlx`.

### Validation

- tests des DTO, pagination, filtres, schéma, migrations, diagnostics et atomicité ;
- tests PostgreSQL réels optionnels pilotés par environnement.