v0.2.14-pre.008

CHANGELOG.md

@@ -1,8 +1,16 @@
 <!-- file: CHANGELOG.md -->
-<!-- version: 17 -->
+<!-- version: 18 -->
 
 # Changelog KSP
 
+## 0.2.14 — Program API foundation — 2026-08-28
+
+`0.2.14` introduit `ksp-program-api` comme première API publique extensible du domaine Program, volontairement limitée au décodage d’instructions et indépendante des runtimes supérieurs. La façade réexporte les contrats Core/Interface nécessaires puis possède `ProgramInstructionRecognition` (`NoMatch`, `ProgramMatch`, `ExactMatch`), `ProgramInstructionDecodeOutcome<Decoded>` (`Decoded`, `Unsupported`) et le trait `ProgramInstructionDecoder: Send + Sync`. L’output `Decoded` reste possédé par l’implémentation et ne reçoit aucun bound implicite `Debug`, `Clone`, `Send` ou `Sync`; les erreurs réelles restent dans le `Result` Core. Les Program IDs sont des `Pubkey` opaques : une implémentation externe peut prendre en charge un programme absent du registry Core sans enum centrale fermée, `Any`, JSON, descriptor global ni registry runtime.
+
+Le graphe normal final reste strictement `ksp-program-api -> ksp-core-lib + ksp-interface-lib`, Interface dépendant elle-même de Core. Aucun `ksp-program-lib`, codec, serde, logging, réseau, filesystem, environnement, Store, Materializer, Wallet, Config ou Tauri n’entre dans cette foundation. Les canaris public API, implémentation externe, dependency firewall, release completeness et hardening couvrent notamment l’inventaire exact de dix exports crate-root, les trois modules de production, un Program Pubkey non enregistré, l’input Interface maximal de 255 accounts / 10 240 bytes, l’absence d’echo automatique d’un payload hostile et l’absence de claim `dyn` hétérogène. `pre.005-fix.001` corrige uniquement un faux positif cross-crate du scanner Logging provoqué par le motif de test recherché, sans changement fonctionnel. Les gates `pre.006` et `pre.007` passent ensuite audits Rust/Markdown, `cargo check`, Clippy, les 18 tests Program API, ownership Logging et le workspace complet avant la réconciliation documentaire finale.
+
+`prompts/020-V0_3_1_START_PROMPT.md` ouvre `0.3.1 — Store RAW foundation` exclusivement depuis le tag stable `v0.2.14`. Le gate `pre.001` exige également l’archive historique `khadhroony-bot3_v0.5.3-pre.005-fix010.zip` afin d’auditer l’ancien `ks-store`, ses migrations PostgreSQL et ses contrats N1/N2/N3 sous une matrice `REPRENDRE / REDESSINER / REPORTER / REJETER`. L’archive reste une source historique uniquement : `0.3.1` doit créer `ksp-store-api` et `ksp-store-lib` avec PostgreSQL de référence et persistence **RAW seulement**, sans aspirer les contrats CORE/DECODE/SPECIALIZED, les jobs/workers, l’Interface `0.3.2` ni la configuration produit.
+
 ## 0.2.13 — Interface / wire foundation — 2026-08-28
 
 `0.2.13` introduit `ksp-interface-lib` comme première façade wire officielle KSP, volontairement passive et Program-facing. La surface stable réexporte le `Pubkey` canonique de Core, ajoute `ProgramAccountMeta` et `ProgramInstruction` à champs privés avec accessors explicites, conserve l’ordre et les doublons des account metas, accepte les Program Pubkeys opaques et borne l’admission à **255 account metas** et **10 240 octets** de data. Les deux bornes sont des limites d’admission Interface et ne prétendent pas garantir à elles seules le fit d’une transaction Solana top-level. Les erreurs réutilisent le contrat Core `Error/Result` avec uniquement `field`, `actual_len` et `maximum_len`, tandis que le `Debug` de l’instruction n’expose que `program_id`, `account_count` et `data_len`.

Cargo.toml

@@ -1,12 +1,12 @@
 # file: Cargo.toml
-# version: 320
+# version: 321
 
 [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-wallet-lib"]
 
 [workspace.package]
-version = "0.2.14-pre.7"
+version = "0.2.14-pre.8"
 edition = "2024"
 license = "MIT"
 repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

ROADMAP.md

@@ -1,5 +1,5 @@
 <!-- file: ROADMAP.md -->
-<!-- version: 91 -->
+<!-- version: 92 -->
 
 # Roadmap KSP
 
@@ -58,7 +58,7 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U
 - [X] `0.2.11` — Off-chain price transport stable : `ksp-offchain-transport-lib` expose SOL/USD via huit adapters REST `reqwest` sans SDK provider, décimal exact, sémantiques/provenance explicites, registry/availability/rate limits et refresh single/many/all génériques ; Config `std.offchain_transport` construit le service sans dépendance inverse, DexScreener reste lié à une paire explicite sans discovery, aucun consensus/fallback automatique n’est introduit, et le smoke live keyless final passe 7/7 après correction CoinMarketCap V2.
 - [X] `0.2.12` — SOL Prices Desk + projection prix Wallet stables : HID provider-neutral avec refresh row/selected/all et batch `1..=64`, observations/timestamps exacts sans polling/consensus, puis refresh balance Wallet enrichi d’une moyenne SOL/USD consumer-owned et d’un équivalent USD exact best-effort ; smoke live de composition, workspace complet et bundles Tauri Linux validés.
 - [X] `0.2.13` — Interface / wire foundation stable : `ksp-interface-lib` expose `Pubkey`, `ProgramAccountMeta` et `ProgramInstruction` passifs, admission bornée à 255 account metas / 10 240 bytes, erreurs et `Debug` sans payload hostile, façade crate-root et consumer externe canaris ; graphe strict `Interface -> Core`, sans serde/codec générique, `solana-instruction`, réseau ni logging runtime.
-- [ ] `0.2.14` — Introduire `ksp-program-api` comme premier contrat Program extensible, sans imposer encore `ksp-program-lib` complet ; `pre.001` doit auditer la base stable `v0.2.13` et l’archive historique `khadhroony-bot3_v0.5.3-pre.005-fix010.zip`, puis classer reconnaissance/decode/outcomes/proofs/préparation sous `REPRENDRE / REDESSINER / REPORTER / REJETER` avant de figer la surface.
+- [X] `0.2.14` — Program API foundation stable : `ksp-program-api` expose une surface instruction-only ouverte avec `ProgramInstructionRecognition`, `ProgramInstructionDecodeOutcome<Decoded>` et `ProgramInstructionDecoder`; implémentation externe avec Program Pubkey opaque validée, 10 exports crate-root / 3 modules de production verrouillés, graphe strict Core + Interface, sans registry/runtime/serde/codec/Store/Materializer/Execution. Le prompt `0.3.1` prépare Store RAW-only.
 
 ### TODO/IDEAS — providers Yellowstone non planifiés
 

deltas/0.2.14/pre.008.md

@@ -0,0 +1,259 @@
+<!-- file: deltas/0.2.14/pre.008.md -->
+<!-- version: 1 -->
+
+# Delta `0.2.14-pre.008` — préparation de publication et prompt `0.3.1`
+
+## 1. Base requise
+
+```text
+0.2.14-pre.007
+workspace.package.version = 0.2.14-pre.7
+```
+
+Le gate opérateur de `pre.007` fourni le 28 août 2026 est intégralement vert :
+
+```text
+cargo fmt --all                                      PASS
+audit Rust général / exports / workspace             PASS
+audit Markdown                                       PASS — 175 tables / 125 fichiers
+cargo check --workspace                              PASS
+cargo clippy --workspace --all-targets               PASS
+cargo test -p ksp-program-api                        PASS — 18 tests Rust
+cargo test -p ksp-logging-lib --test ownership       PASS — 2 tests
+cargo test --workspace                               PASS
+```
+
+Les tests live/bench explicitement `ignored` restent volontairement hors de ce gate documentaire.
+
+`pre.007` a fermé la réconciliation durable de `ksp-program-api`, des indexes, du plan et de la validation sans rouvrir `CHANGELOG.md`, `ROADMAP.md` ni le prompt suivant.
+
+## 2. Objectif
+
+Dernière prerelease avant `rel.001`, strictement limitée à la préparation de publication :
+
+- ajouter l'entrée préparatoire stable `0.2.14` dans `CHANGELOG.md` ;
+- fermer `0.2.14` dans `ROADMAP.md` ;
+- produire `prompts/020-V0_3_1_START_PROMPT.md` ;
+- bump mécanique de la version workspace vers `0.2.14-pre.8` ;
+- ne rouvrir aucun code, test, README/USAGE, plan, validation, architecture ou règle normative.
+
+## 3. Version Cargo
+
+Publication non-fix de prerelease :
+
+```text
+0.2.14-pre.7
+-> 0.2.14-pre.8
+```
+
+Aucune crate membre ne redéfinit localement la version.
+
+## 4. Changelog / Roadmap
+
+`CHANGELOG.md` résume la surface stable candidate `0.2.14` :
+
+```text
+ksp-program-api instruction-only
+ProgramInstructionRecognition
+ProgramInstructionDecodeOutcome<Decoded>
+ProgramInstructionDecoder: Send + Sync
+10 exports crate-root / 3 modules de production
+implémentation externe avec Program Pubkey opaque
+Core + Interface uniquement
+aucun registry/runtime/serde/codec/Store/Materializer/Execution
+18 tests Program API au gate final
+```
+
+`ROADMAP.md` passe `0.2.14` à `[X]` et conserve `0.3.1` comme prochaine release ouverte :
+
+```text
+ksp-store-api + ksp-store-lib
+PostgreSQL de référence
+RAW seulement
+```
+
+## 5. Prompt `0.3.1`
+
+Le nouveau prompt a été confronté à :
+
+```text
+docs/rules/PROMPT_STRUCTURE.md
+docs/rules/VERSION_WORKFLOW.md
+docs/rules/FILE_CONTRACTS.md
+docs/rules/RULES_KSP.md
+docs/rules/RULES_DEPENDENCIES.md
+
+docs/architecture/002-LAYERS_AND_DEPENDENCIES.md
+docs/architecture/003-COMPONENT_CONTRACTS.md
+docs/architecture/004-COMPONENT_INVENTORY.md
+docs/architecture/005-DEPENDENCY_GRAPH.md
+docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md
+docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md
+
+prompts/018-V0_2_13_START_PROMPT.md
+prompts/019-V0_2_14_START_PROMPT.md
+```
+
+L'archive historique suivante a également été reconnue pour déterminer si elle devait être requise dans la prochaine session :
+
+```text
+khadhroony-bot3_v0.5.3-pre.005-fix010.zip
+```
+
+Elle contient notamment :
+
+```text
+ks-store/**
+ks-store/migrations/postgres/**
+config/store.config.json
+config/schemas/store.config.schema.json
+ks-config/src/store.rs
+docs/architecture/STORAGE_ARCHITECTURE.md
+docs/guides/POSTGRES_STORAGE.md
+docs/plans/V0_5_3_KS_STORE_NORMALIZATION_PLAN.md
+```
+
+Conclusion : **l'archive est obligatoire pour `0.3.1-pre.001`**, mais seulement comme source historique à classer sous :
+
+```text
+REPRENDRE / REDESSINER / REPORTER / REJETER
+```
+
+L'ancien `ks-store` couvre RAW + CORE + DECODE/materialization et ne doit donc pas être recopié dans `0.3.1`.
+
+Le prompt protège explicitement les frontières :
+
+```text
+0.3.1  Store API + PostgreSQL RAW-only
+0.3.2  wires génériques Interface acquisition/CORE
+0.3.3  Job API + backfill RAW
+0.3.4  application backfill/inspection RAW
+plus tard CORE -> DECODE -> SPECIALIZED
+```
+
+Il impose en `pre.001` :
+
+```text
+audit base stable
+audit kbot3 Store
+audit PostgreSQL + dépendance Rust candidate avec sources actuelles
+inventaire RAW minimal
+ownership API/impl/composition
+dependency graph
+API backend-agnostic candidate
+schema PostgreSQL RAW candidate
+migration strategy
+threat model
+PostgreSQL integration strategy
+sizing + prévision souple recalibrée
+```
+
+## 6. Prévision souple intégrée au prompt
+
+La prévision initiale réserve distinctement :
+
+```text
+pre.001  audit/sizing
+pre.002  scaffold API + lib
+pre.003  contrats RAW
+pre.004  Store API + backend externe canari
+pre.005  PostgreSQL runtime foundation
+pre.006  schema/migrations RAW
+pre.007  writes/idempotence/atomicité
+pre.008  reads/pagination/notification si retenue
+pre.009  hardening/completeness
+pre.010  gate PostgreSQL réel
+pre.011  réconciliation documentaire
+pre.012  préparation de publication
+rel.001  publication stable
+```
+
+Cette prévision reste souple et doit être recalibrée par `0.3.1-pre.001` selon le scope RAW réel.
+
+## 7. Fichiers ajoutés
+
+```text
+prompts/020-V0_3_1_START_PROMPT.md
+deltas/0.2.14/pre.008.md
+```
+
+## 8. Fichiers modifiés
+
+```text
+Cargo.toml
+CHANGELOG.md
+ROADMAP.md
+```
+
+## 9. Fichiers supprimés
+
+Aucun.
+
+## 10. Surfaces explicitement non rouvertes
+
+```text
+README.md
+RULES.md
+.env.example
+config/**
+crates/**
+docs/**
+prompts/001..019
+```
+
+En particulier :
+
+```text
+crates/ksp-program-api/**
+docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md
+docs/validation/017-V0_2_14_PROGRAM_API.md
+docs/architecture/**
+```
+
+## 11. Validations de préparation
+
+À exécuter sur l'arbre reconstruit :
+
+```text
+audit Rust workspace
+audit Markdown
+contrôle exact du payload overlay
+contrôle des versions/file headers
+contrôle qu'aucun fichier hors lane n'est modifié
+```
+
+Aucun résultat Cargo nouveau n'est revendiqué par la génération de ce delta.
+
+## 12. Gate opérateur
+
+```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.2.14
+cargo check --workspace
+cargo clippy --workspace --all-targets
+cargo test -p ksp-program-api
+cargo test -p ksp-logging-lib --test ownership
+cargo test --workspace
+```
+
+Aucun smoke réseau/live ni nouveau graphe Cargo n'est requis : cette lane ne modifie ni code, ni dépendance, ni runtime.
+
+## 13. Étape suivante
+
+Si le gate reste vert :
+
+```text
+0.2.14-rel.001
+```
+
+La publication stable devra être strictement mécanique :
+
+```text
+workspace.package.version = 0.2.14
+delta deltas/0.2.14/rel.001.md
+commit de publication
+tag stable v0.2.14 après validation opérateur
+```
+
+`rel.001` ne doit modifier ni `CHANGELOG.md`, ni `ROADMAP.md`, ni le prompt `0.3.1`, sauf anomalie découverte qui renverrait d'abord vers une prerelease dédiée conformément au workflow.