v0.3.4-pre.013

CHANGELOG.md

@@ -1,8 +1,20 @@
 <!-- file: CHANGELOG.md -->
-<!-- version: 22 -->
+<!-- version: 23 -->
 
 # Changelog KSP
 
+## 0.3.4 — Store/PostgreSQL RawAccountState + complétude RAW — 2026-08-31
+
+`0.3.4` complète la seconde vertical slice RAW physique sur le couple `ksp-store-lib` / `ksp-store-postgres-lib` et ferme la conformance PostgreSQL des **10 capabilities** backend-agnostic de `ksp-store-api` : les six capabilities `RawTransaction*` acquises en `0.3.3` restent intactes et les quatre capabilities `RawAccountStateRead`, `RawAccountStateWrite`, `RawAccountObservationRead` et `RawAccountObservationWrite` sont désormais implémentées par `PostgresBackend` puis dispatchées par la façade `Store`. La séparation reste stricte : les consommateurs ordinaires passent par `ksp-store-lib`, le backend PostgreSQL conserve SQL/driver/pool/TLS/migrations privés, et la façade reste compilable/testable sans backend via `--no-default-features`.
+
+La migration additive V002 introduit `ksp_raw_account_states` et `ksp_raw_account_observations` au-dessus de V000/V001 sans modifier leurs bytes. L'identité canonique account est `(pubkey, slot, state_hash)` : plusieurs états d'un même compte dans un même slot restent représentables lorsque `state_hash` diffère, tandis qu'une collision sur la référence complète déclenche une comparaison exacte de `lamports`, `owner`, `executable`, `rent_epoch` et `data` avant de conclure à l'idempotence ou à `store_api.raw_conflict`. Les `u64` physiques utilisent `NUMERIC(20,0)`, les clés/hashes/signatures utilisent des `BYTEA` de largeur contrainte, et les bytes account restent complets jusqu'à la borne KSP de 16 MiB. V002 contient exactement 32 ressources gérées et son checksum final est `ff21605ed45f7ab4c0f92bbb692700b4118a9488b04d50a31d259ac59bdb550e`; V000 et V001 restent respectivement `d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450` et `31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51`.
+
+L'acquisition `RawAccountState + RawAccountObservation` est transactionnelle : `INSERT ... ON CONFLICT DO NOTHING`, lecture/verrouillage du canonical en collision, comparaison exacte et rollback complet lorsque l'observation diverge. Une observation supplémentaire vérifie la référence existante sous transaction et ne crée jamais implicitement son state. Les métadonnées Yellowstone `is_startup`, `transaction_signature` et `write_version` restent optionnelles et observation-only ; aucune FK transaction n'est inventée. La navigation account utilise une keyset `(slot, pubkey, state_hash)` ASC/DESC, avec filtre pubkey optionnel et cursor KSPA V1 opaque de 109 octets lié au réseau, au filtre, au range, à la direction et à la famille afin d'empêcher les replays cross-query/cross-family. Aucun `OFFSET`, plafond métier de batch, index owner/provider/time ou lifecycle destructif account n'est introduit.
+
+Les gates de clôture valident audits Rust/Markdown, `cargo check --workspace`, Clippy all-targets, tests ciblés Store/API/PostgreSQL/Config, `cargo test --workspace`, façade sans feature PostgreSQL et graphes Cargo. Le live `postgres_raw_account_live` passe sur **PostgreSQL 17** avec bootstrap V000/V001/V002, round-trip des bytes et du domaine `u64`, idempotence/conflit, états distincts même pubkey+slot, observations/metadata optionnelles, pagination/cursors, concurrence, annulation/rollback et coexistence `RawTransaction`. La réconciliation documentaire finale est ensuite validée sans réouvrir code ni migrations.
+
+`prompts/024-V0_3_5_START_PROMPT.md` ouvre `0.3.5` sur `ksp-interface-lib` uniquement. Cette release doit réauditer les surfaces d'acquisition actuelles et matérialiser seulement les modèles passifs/event-only réellement partagés, sans recopier `RawTransaction`/`RawAccountState`, sans créer un event bus et sans déplacer les DTOs provider/transport. Les candidats logs, slot/root/slotsUpdates, transaction status et vote sont traités par matrice sémantique ; une famille reste reportée si la convergence ou le consumer réel n'est pas démontré. L'archive historique kbot3 n'est pas requise pour ce gate : les sources de vérité sont la base KSP stable et les contrats officiels actuels des transports concernés.
+
 ## 0.3.3 — Store/PostgreSQL RawTransaction vertical slice — 2026-08-30
 
 `0.3.3` complète la première vertical slice RAW physique sur le couple `ksp-store-lib` / `ksp-store-postgres-lib` sans modifier les contrats backend-agnostic acquis dans `ksp-store-api`. `PostgresBackend` et la façade `Store` implémentent désormais les six capabilities `RawTransactionRead`, `RawTransactionWrite`, `RawTransactionObservationRead`, `RawTransactionObservationWrite`, `RawTransactionRetentionRead` et `RawTransactionRetentionWrite`. Une base PostgreSQL reste liée à un unique `RawNetworkId` par `ksp_store_identity`; le mauvais réseau est refusé avant I/O, les slots `u64` sont conservés exactement en `NUMERIC(20,0)`, et la migration logique V001 reste découpée en ressources tables/contraintes/indexes avec vérification de compatibilité du schéma effectif.

Cargo.toml

@@ -1,12 +1,12 @@
 # file: Cargo.toml
-# version: 380
+# version: 381
 
 [workspace]
 resolver = "3"
 members = ["crates/ksp-app-config-desk", "crates/ksp-app-solprices-desk", "crates/ksp-app-wallet-desk", "crates/ksp-config-lib", "crates/ksp-core-lib", "crates/ksp-interface-lib", "crates/ksp-logging-lib", "crates/ksp-offchain-transport-lib", "crates/ksp-onchain-transport-lib", "crates/ksp-program-api", "crates/ksp-store-api", "crates/ksp-store-lib", "crates/ksp-store-postgres-lib", "crates/ksp-wallet-lib"]
 
 [workspace.package]
-version = "0.3.4-pre.12"
+version = "0.3.4-pre.13"
 edition = "2024"
 license = "MIT"
 repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

ROADMAP.md

@@ -1,5 +1,5 @@
 <!-- file: ROADMAP.md -->
-<!-- version: 97 -->
+<!-- version: 98 -->
 
 # Roadmap KSP
 
@@ -96,8 +96,8 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
 - [X] `0.3.1` — `ksp-store-api` stable : modèles N1 RAW backend-agnostic `RawTransaction` et `RawAccountState` avec observations, provenance, payload/hash/timestamps bornés, 10 capabilities object-safe, queries cursorisées sans plafond métier arbitraire, outcomes idempotence/conflit et lifecycle logique rétention/tombstone/force-rehydrate ; aucun backend physique, Config, runtime Store, notification dédiée ni surface STRUCTURAL/DECODED/DOMAIN.
 - [X] `0.3.2` — `ksp-store-lib` + `ksp-store-postgres-lib` stables comme fondation runtime/backend PostgreSQL : feature `postgres` par défaut, `Store` lié à un unique `RawNetworkId`, Config `std.store` avec targets/bases `devnet`/`mainnet`/`testnet`, pool Deadpool borné, `tokio-postgres`, TLS Rustls `Disabled`/`VerifyFull`, moteur de migrations privé `V000` + SHA-256/advisory lock, health/readiness portable et close borné. Gate complet + PostgreSQL réel major 17 verts ; aucune table/capability `RawTransaction`/`RawAccountState` métier n'est encore ajoutée.
 - [X] `0.3.3` — Vertical slice PostgreSQL `RawTransaction` complète sur `ksp-store-lib` + `ksp-store-postgres-lib` : six capabilities transaction/observation/rétention, V001 physique liée à un réseau, acquisition canonical+observation atomique, idempotence/conflit, get/list keyset cursorisé, archive/purge/tombstone/ForceRehydrate, hardening des erreurs et du schéma, concurrence et rollback validés sur PostgreSQL 17.
-- [ ] `0.3.4` — Étendre le même couple avec `RawAccountState` + `RawAccountObservation` : quatre capabilities account, migration additive au-dessus de V000/V001, acquisition state+observation atomique, idempotence/conflit, get/list cursorisé, puis complétude des dix capabilities RAW, indexes justifiés par les queries et hardening PostgreSQL cross-family final.
-- [ ] `0.3.5` — Étendre `ksp-interface-lib` uniquement avec les modèles passifs/events réellement partagés par les premiers consumers d’acquisition, sans dupliquer les modèles persistants de `ksp-store-api`.
+- [X] `0.3.4` — Vertical slice PostgreSQL `RawAccountState` complète sur `ksp-store-lib` + `ksp-store-postgres-lib` : quatre capabilities account ajoutées aux six transaction pour une conformance RAW 10/10, V002 additive de 32 ressources au-dessus de V000/V001 immuables, state+observation atomiques, idempotence/conflit exacts, metadata Yellowstone observation-only, get/list keyset `(slot,pubkey,state_hash)` avec cursor KSPA anti-replay, hardening cross-family et live validé sur PostgreSQL 17 sans rétention destructive account.
+- [ ] `0.3.5` — Étendre `ksp-interface-lib` uniquement avec les modèles passifs/event-only dont une matrice des surfaces HTTP/WS/Yellowstone/Helius démontre la sémantique réellement partagée et le besoin consumer ; auditer notamment logs, slot/root/slotsUpdates, transaction status et vote, sans dupliquer `RawTransaction`/`RawAccountState`, sans event bus et sans dépendance Interface vers Transport/Store.
 - [ ] `0.3.6` — Introduire `ksp-job-api` et un premier job de backfill historique concret consommant `ksp-store-lib`, avec policy/batch-size/progression possédés par le job et non par Store.
 - [ ] `0.3.7` — Introduire une application spécialisée de backfill/inspection RAW.
 - [ ] Compléter ensuite la couche RAW avec le worker/service live, son contrôle et les outils d’exploitation réellement nécessaires avant de passer à la couche de normalisation générique suivante.
@@ -105,7 +105,7 @@ RAW -> STRUCTURAL -> DECODED -> DOMAIN
 ### TODO/IDEAS — taxonomie N1, processing et rétention
 
 - [ ] **TODO** — maintenir la matrice d’admission HTTP/WS/gRPC/provider lors de toute nouvelle famille N1 : plusieurs sources ne convergent vers un même struct que si elles satisfont la même sémantique sans perte.
-- [X] `RawAccountState` + observation — contrat commun stabilisé en `0.3.1` avec bytes complets + slot, provenance séparée et enrichissements source-specific optionnels ; la persistence PostgreSQL physique reste réservée à `0.3.4`.
+- [X] `RawAccountState` + observation — contrat commun stabilisé en `0.3.1` avec bytes complets + slot, provenance séparée et enrichissements source-specific optionnels ; la persistence PostgreSQL physique est complétée en `0.3.4` avec les quatre capabilities account et la conformance RAW 10/10.
 - [ ] **TODO** — `TransactionStatusObservation` : réauditer `signatureSubscribe`, `getSignatureStatuses`, Yellowstone TransactionStatus et extensions provider lorsqu’un consumer réel apparaît ; ne pas fusionner snapshot, transition et update dans un modèle Option-soup.
 - [ ] **TODO** — logs realtime : conserver `logMessages` dans `RawTransaction` jusqu’à la décomposition STRUCTURAL ; traiter `logsSubscribe` comme event-only candidat et décider son contrat passif dans `ksp-interface-lib`, sans table Store par défaut. Le format canonique d’un wake-up « donnée persistée disponible » reste distinct et appartient à `ksp-store-api` conformément à `KSP-NOTIFY-*`, mais ne sera matérialisé qu’avec un publisher/consumer réel.
 - [ ] **TODO** — slot/root/slotsUpdates et vote : ne créer un modèle passif commun que si un consumer realtime réel et une sémantique cross-ledger/provider justifient le contrat ; aucune persistence Store par défaut.

deltas/0.3.4/pre.013.md

@@ -0,0 +1,283 @@
+<!-- file: deltas/0.3.4/pre.013.md -->
+<!-- version: 1 -->
+
+# Delta `0.3.4-pre.013` — préparation de publication et prompt `0.3.5`
+
+## 1. Base requise
+
+Base directe attendue :
+
+```text
+0.3.4-pre.012
+workspace.package.version = 0.3.4-pre.12
+```
+
+Le gate opérateur de `pre.012`, exécuté le **31 août 2026**, est entièrement vert : audits Rust/Markdown, `cargo check --workspace`, Clippy all-targets, tests ciblés Store/API/PostgreSQL/Config et `cargo check -p ksp-store-lib --no-default-features` passent.
+
+Le gate Markdown confirme :
+
+```text
+240 tables / 151 fichiers
+```
+
+`pre.012` n'a rouvert ni code fonctionnel ni migration ; la préparation de publication peut donc commencer sans correctif intermédiaire.
+
+## 2. Objectif
+
+Dernière prerelease avant `rel.001`, strictement limitée à la préparation de publication minimale définie par `VER-LIFECYCLE-003` :
+
+```text
+workspace.package.version -> 0.3.4-pre.13
+finalisation publication de CHANGELOG.md
+clôture de 0.3.4 et précision de 0.3.5 dans ROADMAP.md
+création de prompts/024-V0_3_5_START_PROMPT.md
+delta pre.013
+```
+
+Aucun README, USAGE, plan, validation, architecture, règle, source Rust, test, Config, schema ou migration n'est rouvert.
+
+## 3. Version
+
+Conformément à `VER-ID-009` :
+
+```text
+workspace.package.version = 0.3.4-pre.13
+```
+
+Le header du `Cargo.toml` racine est incrémenté uniquement parce que ce fichier est réellement modifié.
+
+## 4. `CHANGELOG.md`
+
+Une entrée stable `0.3.4` est ajoutée en tête et synthétise :
+
+```text
+RAW capabilities Store/PostgreSQL 10/10
+4 RawAccount* ajoutées aux 6 RawTransaction*
+V002 additive RawAccountState/RawAccountObservation
+32 ressources V002
+checksum V002 ff21605ed45f7ab4c0f92bbb692700b4118a9488b04d50a31d259ac59bdb550e
+V000/V001 immuables
+u64 exact NUMERIC(20,0)
+bytes account complets <= 16 MiB
+acquisition state+observation atomique
+idempotence/conflit exacts
+observation supplémentaire reference-guarded
+metadata Yellowstone observation-only
+pagination keyset (slot,pubkey,state_hash)
+cursor KSPA V1 109 bytes anti-replay
+aucune rétention destructive account
+live PostgreSQL 17 vert
+workspace + no-default-features + graphes verts
+```
+
+Le changelog référence également le prompt `0.3.5` et précise que l'archive kbot3 n'y est pas requise.
+
+## 5. `ROADMAP.md`
+
+L'entrée `0.3.4` passe à `[X]` et décrit la surface stable effectivement validée.
+
+L'entrée `0.3.5` est précisée sans préjuger du résultat de son `pre.001` :
+
+```text
+ksp-interface-lib uniquement
+matrice HTTP/WS/Yellowstone/Helius
+logs / slot-root-slotsUpdates / transaction status / vote à auditer
+seuls les faits event-only réellement convergents et utiles sont matérialisés
+aucune duplication RawTransaction/RawAccountState
+aucun event bus
+aucune dépendance Interface -> Transport/Store
+```
+
+Les étapes `0.3.6` et `0.3.7` restent inchangées.
+
+## 6. Prompt `0.3.5`
+
+Le nouveau prompt ouvre :
+
+```text
+0.3.5 — ksp-interface-lib : modèles passifs/event-only réellement partagés
+```
+
+Base autoritaire :
+
+```text
+v0.3.4
+```
+
+Le `pre.001` est réservé à :
+
+```text
+lecture règles/architecture
+inventaire Interface actuel
+inventaire Store RAW 10/10
+inventaire des surfaces HTTP/WS/gRPC/provider event-like
+identification des consumers
+matrice producer -> nature de fait
+matrice de convergence sémantique
+ownership Interface/Transport/Store/composition
+anti-duplication RawTransaction/RawAccountState
+API sketch des seuls types admis
+bornes / Debug / Clone / non_exhaustive
+graphe cible
+threat model
+sizing
+plan 026 + validation 022
+```
+
+Le prompt interdit une grande enum `Event`, l'Option-soup, les DTOs provider promus tels quels, un event bus, une nouvelle persistence et tout codec/logging runtime non justifié.
+
+## 7. Archive historique
+
+`0.3.5` **n'exige pas** :
+
+```text
+khadhroony-bot3_v0.5.3-pre.005-fix010.zip
+```
+
+La raison est explicite dans le prompt : l'autorité de cette tranche est la sémantique actuelle déjà implémentée dans KSP, complétée par les sources officielles actuelles HTTP/WS/Yellowstone lorsque nécessaire. Un ancien modèle d'events ne doit pas piloter le contrat public par inertie.
+
+## 8. Prévision souple `0.3.5`
+
+Le prompt réserve :
+
+```text
+pre.001  audit consumers/sémantiques/ownership + sizing
+pre.002  première famille passive retenue
+pre.003  famille supplémentaire seulement si justifiée
+pre.004  API publique + consumer externe + anti-duplication
+pre.005  hardening/completeness Interface
+pre.006  gate technique final
+pre.007  réconciliation documentaire
+pre.008  préparation publication
+rel.001  publication stable
+```
+
+Le nombre réel de familles et de prereleases reste recalibrable par `pre.001` ; aucun quota minimal d'events n'est imposé.
+
+## 9. Fichiers ajoutés
+
+```text
+prompts/024-V0_3_5_START_PROMPT.md
+deltas/0.3.4/pre.013.md
+```
+
+## 10. Fichiers modifiés
+
+```text
+Cargo.toml
+CHANGELOG.md
+ROADMAP.md
+```
+
+## 11. Fichiers supprimés
+
+```text
+aucun
+```
+
+## 12. Surfaces explicitement non rouvertes
+
+```text
+README.md
+RULES.md
+crates/**
+docs/**
+config/**
+migrations/**
+prompts/001..023
+```
+
+Hormis le nouveau delta, aucun fichier sous `docs/` ou `crates/` n'est modifié.
+
+## 13. Migrations
+
+Aucune migration n'est modifiée.
+
+Les checksums stables restent :
+
+```text
+V000 d29068b8c13b9dc0cc9ef6aaadd0fa12d41e0fe4c56541a1118c4bfc846a1450
+V001 31488cda2f08f3f46c4cdbdbb6c18c243662fada02eac4487040c8735d72cc51
+V002 ff21605ed45f7ab4c0f92bbb692700b4118a9488b04d50a31d259ac59bdb550e
+```
+
+## 14. Validations exécutées pendant la génération
+
+```text
+python3 scripts/audit_rust_workspace_rules.py
+-> General Rust rule audit: clean
+-> Rust export completeness audit: 0 candidate(s)
+-> KSP workspace Rust rule audit: clean
+
+python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.4
+-> Markdown table audit: clean (240 table(s), 153 file(s))
+
+scope exact pre.012 -> pre.013
+-> 2 fichiers ajoutés
+-> 3 fichiers modifiés
+-> aucun fichier supprimé
+-> DIFF_SCOPE=PASS
+
+crates/** inchangé
+-> PASS
+
+docs/** inchangé
+-> PASS
+
+config/** inchangé
+-> PASS
+
+migrations/** byte-identiques
+-> PASS
+```
+
+Les cinq fichiers de la lane minimale sont donc les seuls fichiers ajoutés/modifiés.
+
+## 15. Validations non exécutées pendant la génération
+
+La toolchain Cargo/Rust opérateur n'est pas supposée disponible dans l'environnement de génération. Aucun `cargo check`, Clippy ou test Cargo post-overlay n'est revendiqué sans exécution réelle.
+
+Aucun live PostgreSQL supplémentaire n'est requis par cette tranche : `pre.013` ne modifie ni code, ni tests, ni migrations.
+
+## 16. Gate opérateur demandé
+
+```bash
+cargo fmt --all
+python3 scripts/audit_rust_workspace_rules.py
+python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.4
+cargo check --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-store-api
+cargo test -p ksp-store-lib
+cargo test -p ksp-store-postgres-lib
+cargo test -p ksp-config-lib
+cargo check -p ksp-store-lib --no-default-features
+```
+
+## 17. Décisions prises
+
+```text
+0.3.4 est techniquement/documentairement fermé avant publication
+0.3.5 reste limité à ksp-interface-lib et à ses docs/tests propres
+les events persistants/replayables restent Store API
+les DTOs protocol/provider restent Transport
+aucun event bus n'est ouvert
+aucune archive kbot3 n'est requise pour 0.3.5
+les candidats event-only restent soumis à une matrice de convergence en pre.001
+```
+
+## 18. Questions ouvertes
+
+Aucune pour la publication `0.3.4`.
+
+Les questions de sélection exacte des events appartiennent explicitement à `0.3.5-pre.001`.
+
+## 19. Suite
+
+Si le gate `pre.013` est propre :
+
+```text
+0.3.4-rel.001
+```
+
+La livraison `rel.001` reste mécanique et minimale : version Cargo stable + delta uniquement. Elle ne corrige aucun défaut documentaire ou fonctionnel.