khadhroony-bot3/ks-store/CHANGELOG.md

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 ;
• 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 ;

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.