242 lines
20 KiB
Markdown
242 lines
20 KiB
Markdown
<!-- file: ks-store/CHANGELOG.md -->
|
||
<!-- version: 38 -->
|
||
|
||
# CHANGELOG — ks-store
|
||
|
||
## `0.5.3-pre.005`
|
||
|
||
- supprime l’ancien chemin complet `apply_store_schema` / `initialize_store_schema`, devenu mort après l’introduction de l’auto-initialisation additive, et fait utiliser aux tests PostgreSQL le même chemin additif que la production afin de conserver `cargo check` et `cargo clippy` sans warnings ;
|
||
- corrige l’exécution SQLx 0.9 des statements DDL additifs dynamiques en marquant explicitement le SQL généré par `ks-store` avec `sqlx::AssertSqlSafe`, sans modifier la logique d’auto-initialisation additive ;
|
||
- aligne l’ouverture PostgreSQL sur un contrat de compatibilité additive : une ressource gérée existante mais incompatible (colonne, clé primaire/étrangère ou index) provoque une erreur, tandis qu’une ressource simplement absente est classée comme dérive additive ;
|
||
- fait de `auto_initialize_schema` un mécanisme d’extension non destructive : `false` refuse toute ressource gérée manquante, `true` peut créer une table absente, ajouter une colonne absente et recréer les clés/index absents avant validation complète ; aucune colonne existante n’est supprimée, renommée ou modifiée automatiquement ;
|
||
- étend `schema_compatibility_verify` au contrat courant de **16 tables, 248 colonnes, 25 clés PK/FK et 79 index physiques**, avec comparaison de la table cible, des colonnes de clé, des actions FK, de l’unicité, de la méthode B-tree, des expressions/ordres et des prédicats d’index ;
|
||
- remplace le blocage global des objets historiques `kb_sol_*` par une validation de compatibilité limitée aux ressources réellement possédées par `ks-store` ; les tables étrangères ou historiques peuvent désormais coexister sans être interprétées ;
|
||
- dérive le contrat de **248 colonnes gérées sur 16 tables** directement des ressources `CREATE TABLE` embarquées et vérifie le type PostgreSQL, la nullabilité, la précision/échelle `NUMERIC` et la présence des défauts nécessaires aux écritures courantes ;
|
||
- accepte les colonnes additives compatibles mais refuse une colonne additive `NOT NULL` sans défaut sur une table gérée, car les `INSERT` courants pourraient l'omettre ;
|
||
- ajoute le diagnostic `schema_compatibility_verify` et un test PostgreSQL opt-in dans `ks-store`; les consommateurs desktop/pipeline restent sans logique d'introspection PostgreSQL ;
|
||
- remplace les listes Replay Candidates à limite embarquée par des pages `PageRequest` cursorisées et comptées via `CountedPageSlice<T>` ;
|
||
- ajoute un comptage rafraîchi à chaque chargement transaction/program/entity afin que le desktop recalcule le nombre total de blocs sans `OFFSET` ;
|
||
- conserve `MAX_PAGE_SIZE = 500` comme borne repository générique ; la politique de bloc desktop fixe à 500 appartient à `kb-app-demo-desktop` et ne crée aucun contrat UI spécifique dans `ks-store` ;
|
||
- ajoute une pagination comptée générique de `k_sol_mat_outputs` avec curseur `(slot, id)` et groupes bornés de contraintes structurelles JSON, utilisés à l’identique par le `COUNT` et la page afin que les totaux reflètent exactement les filtres visibles sans introduire de connaissance SPL/protocole dans le Store ;
|
||
- ajoute des curseurs stables spécifiques aux ordres transaction `(slot, signature)`, programme `(transaction_count, program_id)` et entité `(transaction_count, entity_value)` ;
|
||
- refuse un curseur transaction réutilisé avec une direction d’ordre différente et maintient les requêtes Replay Candidates sans `OFFSET`.
|
||
|
||
## `0.5.3-pre.004`
|
||
|
||
### Fix `pre.004-delta-fix-003`
|
||
|
||
- corrige deux canaris de source auto-référentiels : leurs assertions négatives analysaient aussi le bloc `#[cfg(test)]` qui contenait lui-même la chaîne interdite ;
|
||
- limite désormais les vérifications de source à la partie production précédant `#[cfg(test)]` dans `account_state_queries.rs` et `invalidation_queries.rs` ;
|
||
- ne modifie aucune requête PostgreSQL ni aucun comportement runtime.
|
||
|
||
|
||
### Fix `pre.004-delta-fix-002`
|
||
|
||
- ajoute les annotations explicites `std::string::String` sur `origin_text` et `status_text` dans le mapper PostgreSQL des observations de compte ;
|
||
- corrige les deux erreurs `E0282` d'inférence générique `read_row<T>()` apparues après la suppression de l'opérateur `?`, sans modifier le contrat ni le comportement du mapper.
|
||
|
||
|
||
### Fix `pre.004-delta-fix-001`
|
||
|
||
- remplace les 53 utilisations accidentelles de l'opérateur `?` introduites dans les nouveaux mappers PostgreSQL account-state/Core replay par une propagation explicite `match` conforme aux règles du workspace ;
|
||
- ne modifie ni les contrats publics, ni le SQL, ni les règles de replay/pagination/invalidation de `pre.004`.
|
||
|
||
|
||
### Repositories et replay
|
||
|
||
- rend le replay N2 -> N3 symétrique pour les instructions top-level et CPI via une union logique `CoreInstructionScope::{TopLevel, Inner}` sans fusionner les deux tables physiques ;
|
||
- remplace la pagination `OFFSET` du contrat Core par un curseur stable `(slot, signature, scope_rank, instruction_path)` et borne les lectures interactives à 500 lignes ;
|
||
- borne séparément les batches Core extraction, decode et account-state à 1 000 entrées afin qu’aucune API publique ne conserve les anciennes limites massives ;
|
||
- rend opérationnel le flux générique N1 `account observation` -> N2 `account state` avec sélection version-aware, idempotence par processing ledger, force replay et conservation du domaine `u64` pour lamports/rent epoch.
|
||
|
||
### Invalidation et lifecycle
|
||
|
||
- invalide les descendants N3 decode/coverage/materialization d’une signature dans la même transaction lorsqu’un graphe Core est remplacé ;
|
||
- invalide les sorties de matérialisation d’un decode remplacé pour l’identité exacte decoder name/version/input et utilise des préfixes de ledger littéraux au lieu de `LIKE` ;
|
||
- recalcule le lifecycle top-level/CPI depuis les descendants réellement courants et empêche une matérialisation d’une ancienne version de decoder de rendre la nouvelle version artificiellement `materialized`.
|
||
|
||
### Index, bornes et observabilité
|
||
|
||
- ajoute quatre index non uniques dédiés à l’ordre de replay CPI et aux recherches de descendants coverage/materialization ; le corpus passe à 240 ressources SQL, 63 index explicites et 79 index attendus avec les PK ;
|
||
- ajoute les canaris de conversion `u64`/`BIGINT` et les limites de batch ;
|
||
- instrumente les opérations PostgreSQL réécrites sous `target: crate::TRACING_TARGET`, `backend="postgres"`, `domain="ks-store.pg"` avec `action`, durée, lignes et résultat, sans SQL brut ni valeur bindée.
|
||
|
||
## `0.5.3-pre.003`
|
||
|
||
### Fix `pre.003-delta-fix-005`
|
||
|
||
- remplace le passage des statements SQLx en `TRACE` par `ConnectOptions::disable_statement_logging`, afin que `ks-store` ne dépende pas directement de la crate `log` uniquement pour `LevelFilter` ;
|
||
- conserve l'ouverture PostgreSQL via `PgConnectOptions` + `connect_with` et la journalisation fonctionnelle propre à `ks-store` sous `target: crate::TRACING_TARGET` ;
|
||
- adapte le canari de connexion pour vérifier explicitement la désactivation du statement logging SQLx.
|
||
|
||
|
||
### Fix `pre.003-delta-fix-004`
|
||
|
||
- configure `PgConnectOptions` pour émettre les statements SQLx ordinaires au niveau `TRACE` avant l'ouverture du pool via `connect_with`, tout en conservant le target tiers `sqlx::query` ;
|
||
- préserve les événements fonctionnels PostgreSQL `ks-store` sous `target: crate::TRACING_TARGET` avec `backend`, `domain` et `action` ;
|
||
- ajoute un canari positif vérifiant le chemin `PgConnectOptions` + `TRACE` + `connect_with`.
|
||
|
||
### Fix `pre.003-delta-fix-003`
|
||
|
||
- corrige la branche `incomplete_signatures` de la sélection N2 -> N3 : le `SELECT` contextualisé projette désormais `stack_height` comme l'exige `CoreInstructionRow` ;
|
||
- extrait cette requête rare dans `INCOMPLETE_DECODE_INPUTS_SQL` et ajoute un test contractuel vérifiant toutes les colonnes attendues par le mapper Core, afin d'éviter une nouvelle dérive requête/DTO.
|
||
|
||
|
||
### Baseline N1-N3 PostgreSQL
|
||
|
||
- corrige le premier delta `pre.003` : fermeture de l'`impl PostgresStore`, appels des helpers privés de tests via `super::` et retrait des validateurs de noms de tables du runtime/re-export crate-root ; ces validateurs restent des canaris privés `#[cfg(test)]`.
|
||
- reconstruit directement le schéma actif sous `k_sol_*` avec un baseline candidat au gel de **16 tables** : les 13 tables historiques conservées plus `k_sol_obs_account_observations`, `k_sol_core_account_states` et `k_sol_core_return_data` révélées par le canari future-decoder ;
|
||
- ajoute `block_time` aux ancres raw/Core transaction, `stack_height` aux contrats top-level/CPI et un lifecycle de processing symétrique pour les CPI ; la reconstruction de Core préserve le parent CPI immédiat lorsque la pile est disponible ;
|
||
- renomme le journal N3 en `k_sol_mat_outputs` et aligne l'API publique sur `MaterializedOutputFilter`, `MaterializedOutputQueryRow` et `list_materialized_outputs` ;
|
||
- réserve sur `k_sol_decode_events` une provenance nullable de schéma externe (`kind/id/version/hash`) afin qu'un futur décodeur IDL puisse tracer son schéma sans remodeler N1/N2/N3.
|
||
|
||
### Ressources et initialisation
|
||
|
||
- corrige `pre.003-delta-fix-002` l'ordre transactionnel des contraintes : les clés primaires référencées sont désormais appliquées avant les clés étrangères ; ajoute un canari couvrant les neuf dépendances FK du baseline afin d'empêcher un nouvel ordre invalide et le rollback complet observé sur base vide ;
|
||
- remplace les migrations historiques `0001` à `0004` et les deux scripts de maintenance monolithiques par **236 ressources PostgreSQL atomiques** sous `migrations/postgres/` : tables, contraintes, index, `TRUNCATE` et `DROP`, une instruction SQL par fichier embarquée par `include_str!` ;
|
||
- centralise l'initialisation dans un seul orchestrateur PostgreSQL transactionnel avec advisory lock ; les initialiseurs raw/Core/decode partiels sont supprimés, y compris dans les tests ;
|
||
- refuse explicitement la présence d'objets historiques `kb_sol_*` au lieu de mélanger les deux namespaces ;
|
||
- remplace la lecture `_sqlx_migrations` comme preuve du schéma courant par la vérification du contrat réellement observé ;
|
||
- étend le résumé backend-agnostique aux catégories physiques `table` et `index`, avec **75 index attendus** sans exposer leurs noms.
|
||
|
||
### Readiness et contrats
|
||
|
||
- conserve explicitement la `returnData` en N2 et enrichit le replay Core v3 avec `block_time`, `stack_height`, parent CPI, contexte top-level et return data ;
|
||
- introduit les DTO N1/N2 génériques d'observation/état de compte nécessaires au futur décodage de layouts inconnus, sans ajouter de structure Anchor/IDL spécifique ; leur ingestion/replay fonctionnel est raccordé dans la tranche repositories/replay ;
|
||
- ajoute un canari workspace imposant `crate::Type` pour les types publics de `ks-store` utilisés dans leur crate propriétaire ;
|
||
- ne crée aucune table DEX/trading ni projection metadata N4 et ne déclare pas encore le gel formel : le snapshot final reste prévu après les validations techniques.
|
||
|
||
## `0.5.3-pre.002-delta-fix-003`
|
||
|
||
- corrige deux appels de helpers strictement privés PostgreSQL qui avaient été qualifiés à tort via `crate::`; ils restent locaux à leur module et ne sont pas réexportés au crate-root ;
|
||
- ne modifie aucun contrat public ni schéma SQL.
|
||
|
||
## `0.5.3-pre.002-delta-fix-002`
|
||
|
||
- remplace les visibilités `pub(in crate::postgres)` par la convention workspace : privé ou `pub(crate)` + réexport crate-root et consommation via `crate::Item` ;
|
||
- ajoute le canari Rust interdisant `pub(in ...)`/`pub(super)` et corrige les reexports `#[cfg(test)]` de `ks-pipeline-demo-scenarios` ;
|
||
- supprime les appels obsolètes à `Store::initialize_store_schema()` : l’initialisation reste possédée par `Store::open()` via la configuration backend ;
|
||
- renomme structurellement les modules, fenêtres, commandes, HTML/TypeScript et DTO `demo_sql_*` en `demo_store_*`, sans attendre la refonte fonctionnelle finale de `pre.005` ;
|
||
- réconcilie le tracing PostgreSQL avec la règle d’un target unique : `target: crate::TRACING_TARGET`, `backend="postgres"`, `domain="ks-store.pg"`, `action=...` ;
|
||
- supprime les helpers/constantes transitoires morts signalés par `cargo check`/Clippy et l’attente Clippy devenue inutile.
|
||
|
||
## `0.5.3-pre.002-delta-fix-001`
|
||
|
||
- corrige les helpers PostgreSQL de validation de noms de tables rendus inaccessibles par la nouvelle frontière privée et aligne leurs appels/tests sur la façade interne `crate::postgres::*` ;
|
||
- supprime les réexports PostgreSQL internes devenus inutiles qui produisaient des warnings et conserve le target générique `ks-store` en l'utilisant réellement à l'ouverture de la façade `Store` ;
|
||
- aligne les nouveaux types publics/crate-publics introduits par `pre.002` sur la règle de qualification `crate::Item` dans leur crate propriétaire.
|
||
|
||
## `0.5.3-pre.002`
|
||
|
||
### Façade et configuration
|
||
|
||
- introduit `Store` et `StoreOpenOptions` comme frontière publique backend-agnostique et confine `PostgresStore`, `PostgresStoreOptions`, `PgPool`, les constantes physiques et les requêtes SQL à l'implémentation privée ;
|
||
- remplace les sections runtime PostgreSQL/SQLite imposées par un code `backend` et un objet `backend_options` opaque jusqu'à son interprétation par `ks-store`, sans créer de dépendance `ks-store -> ks-config` ;
|
||
- retire les quatre anciens traits/DTO historiques sans implémentation réelle et renomme les contrats publics de replay/diagnostic sans préfixe PostgreSQL ;
|
||
- conserve `Store` dans l'état applicatif desktop via une initialisation unique et réutilisable par les commandes/scénarios.
|
||
|
||
### Diagnostics et sécurité
|
||
|
||
- ajoute les résumés génériques de configuration, backend, initialisation et vérification par modèle, sans exposition des noms physiques de tables/index ni des options backend brutes ;
|
||
- masque le descripteur PostgreSQL et sanitise l'erreur de connexion afin qu'aucun DSN/password ne traverse les diagnostics normaux ;
|
||
- introduit le domaine structuré PostgreSQL `ks-store.pg` sous l’unique `target: crate::TRACING_TARGET`, ainsi qu'un canari workspace empêchant les types PostgreSQL/SQLx de sortir de `ks-store` ;
|
||
- adapte les consommateurs Rust et les payloads desktop aux ressources/diagnostics génériques ; le renommage structurel `demo_sql_* -> demo_store_*` est finalisé par `delta-fix-002`, tandis que la refonte fonctionnelle finale reste à la tranche consommateurs.
|
||
|
||
### Portée
|
||
|
||
- ne modifie aucune table ni migration SQL de production : le namespace `k_sol_*`, `block_time`, la symétrie top-level/CPI et les ressources SQL atomiques restent réservés à `pre.003`.
|
||
|
||
## `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`, le renommage structurel `demo_sql_* -> demo_store_*`, la refonte backend-agnostique de `demo_config`/splash et le domaine de tracing PostgreSQL `ks-store.pg` sous l’unique target `ks-store` ;
|
||
- 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.
|