From 7dfe892467897b6b4b4ef98de4b851e28298a9b8 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Fri, 28 Aug 2026 16:50:48 +0200 Subject: [PATCH] v0.2.14-pre.008 --- CHANGELOG.md | 10 +- Cargo.toml | 4 +- ROADMAP.md | 4 +- deltas/0.2.14/pre.008.md | 259 +++++ prompts/020-V0_3_1_START_PROMPT.md | 1463 ++++++++++++++++++++++++++++ 5 files changed, 1735 insertions(+), 5 deletions(-) create mode 100644 deltas/0.2.14/pre.008.md create mode 100644 prompts/020-V0_3_1_START_PROMPT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a0a92a1..7f9d88f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,16 @@ - + # 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`, `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`. diff --git a/Cargo.toml b/Cargo.toml index 5577662..8d6bf6e 100644 --- a/Cargo.toml +++ b/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" diff --git a/ROADMAP.md b/ROADMAP.md index a5dbfe2..0103454 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # 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` 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 diff --git a/deltas/0.2.14/pre.008.md b/deltas/0.2.14/pre.008.md new file mode 100644 index 0000000..f22f086 --- /dev/null +++ b/deltas/0.2.14/pre.008.md @@ -0,0 +1,259 @@ + + + +# 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 +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. diff --git a/prompts/020-V0_3_1_START_PROMPT.md b/prompts/020-V0_3_1_START_PROMPT.md new file mode 100644 index 0000000..856723e --- /dev/null +++ b/prompts/020-V0_3_1_START_PROMPT.md @@ -0,0 +1,1463 @@ + + + +# Prompt de démarrage `0.3.1` — Store RAW foundation + +## 1. Identité de la release et bases exactes requises + +La base KSP attendue est **exclusivement** la release stable : + +```text +v0.2.14 +``` + +La release à ouvrir est : + +```text +0.3.1 — Store RAW foundation +``` + +La première tranche est : + +```text +0.3.1-pre.001 +``` + +Deux archives sont requises au démarrage de la session : + +```text +1. archive opérateur correspondant exactement à KSP v0.2.14 +2. archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip +``` + +Ordre d'autorité : + +```text +v0.2.14 réelle / archive opérateur autorité KSP actuelle +règles + architecture de v0.2.14 autorité normative et architecturale +khadhroony-bot3 historique source d'audit/héritage uniquement +sources PostgreSQL/crates actuelles autorité externe sur le comportement présent +anciens prompts / snippets / mémoire auxiliaires seulement +``` + +L'archive kbot3 **est obligatoire pour le gate `pre.001`**. Elle contient un ancien `ks-store`, des migrations PostgreSQL, une configuration Store et une architecture de persistence suffisamment riches pour éviter de réinventer sans audit les problèmes déjà rencontrés. Elle n'est toutefois jamais une base de code ni une autorité architecturale : l'ancien Store couvre RAW, CORE, DECODE, materialization et processing ledger, alors que `0.3.1` doit rester strictement **RAW-only**. + +Si l'archive historique n'est pas disponible : + +```text +ne pas inventer son contenu depuis la mémoire +ne pas déclarer l'audit d'héritage terminé +ne pas commencer le schéma PostgreSQL fonctionnel +``` + +Ne pas ouvrir `0.3.1` depuis : + +```text +0.2.14-pre.* +0.2.14-pre.*-fix.* +0.2.14-rel.* non encore validé stable +une archive de travail intermédiaire +l'ancien dépôt khadhroony-bot3 comme base de code +un souvenir de session +``` + +À l'ouverture, vérifier au minimum : + +```text +tag Git v0.2.14 si metadata Git disponible +workspace.package.version = 0.2.14 +deltas/0.2.14/rel.001.md présent +prompts/020-V0_3_1_START_PROMPT.md présent +ksp-program-api présent et conforme à la surface stable 0.2.14 +ksp-store-api absent sauf contradiction de la base réelle +ksp-store-lib absent sauf contradiction de la base réelle +archive khadhroony-bot3_v0.5.3-pre.005-fix010.zip disponible +``` + +Si une divergence existe entre ce prompt et la base stable réelle, la base réelle gagne et la divergence devient une sortie explicite de `pre.001`. + +`pre.001` est obligatoirement une tranche **lecture + audit KSP + audit kbot3 + audit PostgreSQL/dependencies + définition RAW + dependency graph + API/backend model + threat model + stratégie migrations/tests + sizing + planification**. + +Aucun schéma PostgreSQL définitif, repository fonctionnel lourd, migration active ni API Store publique définitive ne doit être figé avant la sortie cohérente de ce gate. + +--- + +## 2. Mission et résultat attendu + +La mission de `0.3.1` est d'introduire le premier Store KSP durable sous la séparation : + +```text +ksp-store-api + = contrats backend-agnostic de persistence + +ksp-store-lib + = implémentation PostgreSQL officielle de référence +``` + +La release est volontairement limitée à : + +```text +D1 / RAW uniquement +``` + +Elle ne doit pas ouvrir prématurément : + +```text +D2 / CORE +D3 / DECODE +D4 / SPECIALIZED +``` + +Le résultat attendu à la clôture est un Store RAW suffisamment réel pour : + +```text +représenter un input d'acquisition persistant et replayable pour les catégories retenues +préserver provenance et identité d'idempotence nécessaires +écrire/lire ces faits via une API backend-agnostic +fournir PostgreSQL comme backend officiel de référence +prouver l'atomicité/idempotence attendue sur un PostgreSQL réel +permettre à un backend externe de satisfaire le contrat public sans dépendre de ksp-store-lib +``` + +La release ne doit pas confondre : + +```text +modèle Transport != modèle RAW persistent +Store API != PostgreSQL API +payload replayable != décodage Program +notification de disponibilité != source de vérité du backlog +migration SQL != API publique +Config != Store +``` + +La question centrale de `0.3.1` est : + +> quel est le plus petit contrat RAW backend-agnostic qui conserve assez fidèlement l'acquisition couverte pour permettre un replay ultérieur sans redemander la donnée au provider, tout en restant indépendant des modèles Transport, des wires génériques futurs de `0.3.2` et des couches CORE/DECODE/SPECIALIZED ? + +Le gate `pre.001` peut réduire le nombre de catégories RAW initiales si le scope complet ne tient pas dans une session. Une réduction doit être fonctionnelle et explicitement documentée ; elle ne doit pas être masquée derrière un type « fourre-tout » non justifié. + +--- + +## 3. Sources de vérité internes obligatoires — ordre de lecture + +### 3.1 Règles globales + +Lire d'abord : + +```text +RULES.md +docs/000-README.md + +docs/rules/RULES_GENERAL.md +docs/rules/RULES_KSP.md +docs/rules/RULES_RUST.md +docs/rules/RULES_DEPENDENCIES.md +docs/rules/RULES_DOCUMENTATION.md +docs/rules/FILE_CONTRACTS.md +docs/rules/VERSION_WORKFLOW.md +docs/rules/PROMPT_STRUCTURE.md +``` + +Relire particulièrement : + +```text +KSP-API-001..007 +KSP-CONFIG-001..018 +KSP-NOTIFY-001..006 +KSP-STORE-001..002 +KSP-DATA-001..004 +KSP-PIPE-001..007 + +DEP-KSP-001..005 +DEP-CARGO-001..007 +DEP-LOG-001..012 +DEP-STORE-001..008 +DEP-TRANSPORT-001..005 +DEP-PIPE-001..008 +DEP-WORKER-001..003 +DEP-JOB-001..003 +``` + +Rappels directement structurants : + +```text +ksp-store-api ne dépend pas de ksp-store-lib +ksp-store-api ne dépend pas de Program / Materializer / Transport +ksp-store-lib dépend de ksp-store-api et contient PostgreSQL de référence +ksp-store-lib ne dépend pas des implémentations Transport / Program / Materializer +les conversions Transport -> RAW appartiennent à la composition/pipeline futur +aucun ksp-data-api global +les notifications ne sont qu'un wake-up, jamais le backlog +persistence/commit précèdent toute notification +``` + +Pour tout Rust modifié : + +```bash +cargo fmt --all +python3 scripts/audit_rust_workspace_rules.py +cargo check --workspace +cargo clippy --workspace --all-targets +``` + +Pour tout Markdown touché : + +```bash +python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.1 +``` + +Une commande non exécutée n'est jamais déclarée PASS. + +### 3.2 Architecture durable + +Lire ensuite : + +```text +docs/architecture/000-README.md +docs/architecture/001-PROJECT_OBJECTIVES.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/006-WIRE_AND_PROGRAM.md +docs/architecture/007-EXECUTION_AND_POLICY.md +docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md +docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md +docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md +``` + +Les références centrales de `0.3.1` sont : + +```text +docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md +docs/architecture/005-DEPENDENCY_GRAPH.md +docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md +``` + +Préserver notamment : + +```text +RAW -> CORE -> DECODE -> SPECIALIZED +RAW et CORE indépendants du décodage Program +Store persiste des contrats ; il ne possède ni transport, ni decoder, ni materializer +ksp-store-api backend-agnostic +ksp-store-lib PostgreSQL officiel +première Store release RAW-only +Transport -X-> Store +``` + +### 3.3 État de release précédent à relire + +Lire : + +```text +docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md +docs/validation/017-V0_2_14_PROGRAM_API.md +crates/ksp-program-api/README.md +crates/ksp-program-api/USAGE.md +CHANGELOG.md +ROADMAP.md +``` + +But : préserver les frontières acquises. L'existence de `ksp-program-api` ne justifie aucune dépendance Store -> Program en `0.3.1`. + +--- + +## 4. Audit historique kbot3 obligatoire + +### 4.1 Archive + +Auditer : + +```text +khadhroony-bot3_v0.5.3-pre.005-fix010.zip +``` + +Au minimum : + +```text +ks-store/Cargo.toml +ks-store/README.md +ks-store/USAGE.md +ks-store/TODO.md +ks-store/src/lib.rs +ks-store/src/store.rs +ks-store/src/contracts/** +ks-store/src/postgres/** +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 +``` + +### 4.2 Concepts historiques à classifier + +Produire une matrice : + +```text +REPRENDRE +REDESSINER +REPORTER +REJETER +``` + +Classer au minimum : + +```text +séparation façade Store / PostgreSQL +StoreOpenOptions / backend selection +health/readiness +contracts/dto/raw.rs +contracts/entity/raw.rs +RawTransactionStore +repository traits +pagination +replay contracts +error contracts +schema validation / migration bootstrap +migrations atomiques +constraints/indexes +idempotence / uniqueness +raw transaction table +acquisition observations +processing ledger +CORE tables +DECODE coverage/events +materialization journal +maintenance truncate/drop +Config Store +runtime diagnostics +``` + +### 4.3 Contraintes d'héritage + +Ne pas copier tel quel : + +```text +le monolithe ks-store N1/N2/N3 +les 16 tables historiques +les 240 ressources SQL historiques +les noms physiques k_sol_* historiques +les contrats CORE/decode/materialization +les processing ledgers appartenant à des couches non ouvertes +les DTO JSON génériques uniquement parce qu'ils existaient +les surfaces Config historiques +les dépendances historiques ou leurs versions +``` + +L'audit doit distinguer : + +```text +concept toujours valide +forme historique devenue trop large +contrat qui appartient à 0.3.2+ +contrat incompatible avec les règles KSP actuelles +``` + +--- + +## 5. Sources externes à réauditer au début de `pre.001` + +La release introduit un backend PostgreSQL réel et probablement une nouvelle dépendance Rust de database access. La fraîcheur est donc obligatoire. + +Consulter en priorité des sources primaires actuelles : + +```text +PostgreSQL documentation officielle +crate/repository/documentation officielle du candidat PostgreSQL Rust retenu +Cargo/crates.io pour la version stable réellement courante +``` + +Le candidat historique principal est `sqlx`, mais `pre.001` doit vérifier sa pertinence actuelle avant de l'ajouter. + +Auditer au minimum : + +```text +version stable actuelle +MSRV/rust edition compatibility +runtime TLS/features nécessaires +PostgreSQL feature set +migration support +transactions +query parameter binding +pool settings +statement/query timeout possibilités +error surfaces +compile-time/offline requirements éventuels +features transitives et doublons Cargo +``` + +Ne pas conserver dans le prompt ou le manifeste une version historique de `sqlx` simplement parce que kbot3 l'utilisait. + +Si une alternative à `sqlx` est proposée, comparer explicitement sa valeur pour KSP avant décision. + +PostgreSQL doit également être réaudité sur les types réellement retenus : + +```text +BIGINT / integer bounds +BYTEA si payload binaire retenu +TIMESTAMPTZ / timestamp semantics +JSONB uniquement si un besoin réel le justifie +unique constraints / ON CONFLICT +transaction isolation nécessaire +indexes/pagination choisis +``` + +Ne pas inventer une dépendance ou un type SQL avant que le contrat RAW soit défini. + +--- + +## 6. État stable `v0.2.14` à préserver + +La base acquise contient notamment : + +```text +ksp-core-lib +ksp-logging-lib +ksp-config-lib +ksp-interface-lib +ksp-program-api +ksp-onchain-transport-lib +ksp-offchain-transport-lib +ksp-wallet-lib +applications desktop existantes +``` + +Program API stable : + +```text +ProgramInstructionRecognition +ProgramInstructionDecodeOutcome +ProgramInstructionDecoder +``` + +La direction Program reste : + +```text +ksp-program-api -> Core + Interface +``` + +Store ne doit pas l'inverser ni s'y connecter en `0.3.1` : + +```text +ksp-store-api -X-> ksp-program-api +ksp-store-lib -X-> ksp-program-api +``` + +Transport conserve ses modèles homogènes et sa responsabilité réseau : + +```text +ksp-onchain-transport-lib -X-> ksp-store-api +ksp-onchain-transport-lib -X-> ksp-store-lib +``` + +La conversion future doit rester explicite dans une composition/pipeline : + +```text +transport model + -> conversion RAW explicite + -> ksp-store-api contract + -> backend injecté +``` + +--- + +## 7. Décisions acquises avant `pre.001` + +Les décisions suivantes ne sont pas à redébattre sans contradiction de la base réelle : + +### 7.1 Nommage et split + +```text +ksp-store-api +ksp-store-lib +``` + +`ksp-store-api` est une exception volontaire au suffixe `-lib` : c'est une API publique de backend extensible. + +### 7.2 Backend officiel + +```text +PostgreSQL = backend officiel de référence de ksp-store-lib +``` + +Cette décision ne signifie pas : + +```text +PostgreSQL types dans ksp-store-api +sqlx types dans ksp-store-api +noms physiques de tables dans l'API publique +``` + +### 7.3 Première couche + +```text +0.3.1 = RAW seulement +``` + +Les contrats D2/D3/D4 sont explicitement interdits dans cette release. + +### 7.4 Backend-agnostic + +Un consumer logique doit pouvoir dépendre de `ksp-store-api` sans dépendre de `ksp-store-lib`. + +Une implémentation externe de l'API doit être techniquement possible lorsque le contrat retenu le justifie. + +### 7.5 Notifications + +`ksp-store-api` est l'owner retenu du format canonique de notification/référence quand elle signifie qu'une donnée persistée est disponible. + +Mais : + +```text +le mécanisme concret de diffusion est hors scope +une notification ne remplace jamais une query/backlog Store +publication seulement après commit +``` + +`pre.001` doit décider si le type de référence RAW minimal est assez stabilisé pour introduire ce format maintenant ou s'il doit être reporté tout en conservant l'ownership. + +### 7.6 Configuration + +`ksp-store-lib` ne lit pas lui-même : + +```text +.env +KSP_* / KSPB_* +fichier Config +``` + +`ksp-config-lib` reste seul owner de ces sources. Aucun document `std.store` n'est exigé par `0.3.1` tant qu'aucun lifecycle host n'en a besoin. + +--- + +## 8. Questions réellement ouvertes pour `pre.001` + +Ne pas décider par intuition avant audit : + +### 8.1 Inventaire RAW initial + +Déterminer quelles catégories RAW sont nécessaires dans `0.3.1`. + +Candidats à examiner : + +```text +transaction acquisition +account observation +block/slot acquisition +generic envelope par catégorie +``` + +Le scope doit être assez utile pour préparer `0.3.3` backfill, mais assez petit pour être clôturé dans une session. + +### 8.2 Forme du payload replayable + +Décider comment conserver une acquisition suffisamment fidèle sans : + +```text +dépendre de Transport +faire de Store un owner de wire Solana +inventer un JSON universel +introduire un codec wire concurrent à ksp-interface-lib +``` + +Si des bytes opaques sont retenus, documenter clairement qui possède leur encodage et comment un futur replay sait les interpréter. + +Si un JSON/JSONB est retenu pour une catégorie précise, justifier son statut et ne pas en faire un contrat universel par commodité. + +### 8.3 Identité/idempotence + +Définir pour chaque catégorie retenue : + +```text +clé logique +hash/idempotence key +comportement duplicate +replacement éventuel +origine/provider duplication éventuelle +``` + +Ne pas promettre exactly-once distribué. + +### 8.4 Provenance + +Déterminer les champs publics réellement nécessaires parmi : + +```text +cluster/network +provider +transport/protocol +source/endpoint identity sûre +acquisition role live/backfill/import +observed_at +persisted_at +slot/signature/pubkey selon catégorie +cursor/page/range/checkpoint si pertinent +``` + +Ne jamais stocker ou exposer un secret d'endpoint/credential dans une provenance publique. + +### 8.5 API async/backend extensible + +Décider la forme des contracts `ksp-store-api` : + +```text +traits par capability/repository +façade globale ou composition de traits +futures/async trait strategy +Send/Sync requirements +object safety seulement si un vrai consumer dyn l'exige +transaction abstraction éventuelle +pagination/cursors +health/readiness +``` + +Ne pas ajouter `async-trait`, boxing ou registry backend uniquement pour anticiper un usage non démontré. + +### 8.6 Frontière `ksp-store-api` / `ksp-store-lib` + +Décider quels types appartiennent à API et lesquels restent privés à PostgreSQL : + +```text +RAW DTOs +persistent references +write outcomes +query filters +page cursors +health state +backend open/settings +migration state +pool/transaction handles +SQL error mapping +``` + +### 8.7 Migrations + +Décider : + +```text +layout migrations +bootstrap/upgrade policy +strict validation d'un schéma existant +additive-only éventuel +rollback policy +maintenance scripts ou non +version de schema +``` + +Ne pas reprendre automatiquement le système « une instruction SQL par fichier » de kbot3 sans justification KSP actuelle. + +### 8.8 Test PostgreSQL réel + +Définir un gate reproductible sur un PostgreSQL réel sans transférer l'ownership Config/env vers Store. + +Préférer une stratégie opérateur explicite et sûre : + +```text +DSN fourni uniquement au test live/integration +aucun secret imprimé +aucun DSN dans Debug/Error +base/schema de test isolé +cleanup borné +``` + +Le mécanisme exact doit être choisi en `pre.001`. + +--- + +## 9. Objectifs et livrables + +Sous réserve du sizing `pre.001`, la release doit viser : + +### 9.1 `ksp-store-api` + +Minimum attendu : + +```text +crate *-api déclarative +contrats RAW backend-agnostic retenus +capabilities read/write nécessaires +outcomes/errors via Core +aucun type PostgreSQL/sqlx public +façade crate-root explicite +external backend canary +``` + +Dépendance cible maximale par défaut : + +```text +ksp-store-api +└── ksp-core-lib +``` + +Toute dépendance supplémentaire doit être justifiée par un type réellement nécessaire. Ne pas ajouter `ksp-interface-lib` par symétrie ; `0.3.2` doit rester propriétaire des wires génériques futurs. + +### 9.2 `ksp-store-lib` + +Minimum attendu : + +```text +implémentation PostgreSQL officielle +settings/open contract programmatique +pool/connection private +migrations/schema RAW seulement +write/read RAW +idempotence/atomicité +pagination/query bornée si retenue +health/readiness safe +logging KSP si comportement runtime réel +``` + +Graphe cible : + +```text +ksp-store-lib +├── ksp-store-api +├── ksp-core-lib +├── ksp-logging-lib +└── PostgreSQL dependency candidate retenue +``` + +`ksp-store-lib` ne doit pas dépendre de : + +```text +ksp-onchain-transport-lib +ksp-program-api +ksp-program-lib +ksp-materializer-api +ksp-materializer-lib +ksp-wallet-lib +ksp-config-lib +Tauri +``` + +### 9.3 Documentation + +Créer lors de `pre.001` : + +```text +docs/plans/022-V0_3_1_STORE_RAW_PLAN.md +docs/validation/018-V0_3_1_STORE_RAW.md +``` + +Puis documenter les crates au moment de leur scaffold : + +```text +crates/ksp-store-api/README.md +crates/ksp-store-api/USAGE.md +crates/ksp-store-lib/README.md +crates/ksp-store-lib/USAGE.md +``` + +Les index durables sont réconciliés dans la lane documentaire finale, pas au fil de chaque tranche sans besoin. + +--- + +## 10. Hors périmètre strict + +`0.3.1` n'introduit pas : + +```text +D2 CORE persistence +RAW -> CORE normalizer +CORE replay job +D3 decode/materialization journal +D4 specialized projections +ksp-materializer-api / lib +ksp-program-lib +Program account/event/return-data decoding +ksp-job-api +ksp-job-backfill +ksp-worker-api +ksp-worker-raw-retriever +ksp-pipeline-raw-ingestion-lib sans réutilisation démontrée +application backfill/inspection +nouveau Tauri Desk +transport/provider selection +HTTP/WS/gRPC acquisition +Config std.store par anticipation +notification transport concret +scheduler +orchestrateur +execution/policy/wallet integration +``` + +Également hors scope : + +```text +schéma PostgreSQL N2/N3/N4 +processing ledger DECODE +coverage declarations +materialization outputs +DEX/token/metadata tables +analytics/OHLC +``` + +`0.3.2` reste propriétaire de l'extension `ksp-interface-lib` avec les wires génériques nécessaires aux acquisitions et à la future normalisation CORE. + +`0.3.3` reste propriétaire de `ksp-job-api` + premier backfill concret. + +`0.3.4` reste propriétaire de l'application backfill/inspection RAW. + +--- + +## 11. Contraintes sécurité/API/architecture spécifiques + +### 11.1 Secrets PostgreSQL + +DSN, user, password, TLS material et options sensibles : + +```text +jamais dans Debug +jamais dans Display public +jamais dans ErrorContext arbitraire +jamais dans logs +jamais dans snapshots publics +``` + +Les erreurs d'une dépendance PostgreSQL ne deviennent `source` de `ksp_core_lib::Error` qu'après audit de leur chaîne Debug/source conformément à `RUST-ERR-007`. + +### 11.2 SQL + +Règles minimales : + +```text +bind parameters pour valeurs runtime +aucune concaténation SQL avec input non fiable +noms physiques de tables privés à ksp-store-lib +transactions explicites pour invariants multi-opérations +queries/pagination bornées +``` + +### 11.3 Payloads RAW + +Tout payload potentiellement hostile doit être borné avant copie/allocation non bornée quand la frontière API le permet. + +`Debug` et erreurs ne doivent pas afficher le payload brut. + +Les tailles exactes ne sont pas inventées : `pre.001` les dérive des catégories réellement retenues et des limites Transport/wire existantes. + +### 11.4 Observabilité + +`ksp-store-api` purement déclaratif n'ajoute pas Logging. + +`ksp-store-lib`, en tant que runtime comportemental, utilise `ksp-logging-lib` si instrumentation nécessaire et possède : + +```text +src/constants.rs +pub(crate) const TRACING_TARGET: &str = "ksp-store-lib"; +``` + +Ne jamais émettre : + +```text +SQL brut contenant des valeurs +bind values +DSN +credential +raw payload +``` + +### 11.5 API publique + +Conserver les règles Rust KSP : + +```text +aucun pub mod +réexports explicites crate-root +pas de use non-trait +pas de type sqlx dans la façade publique +pas de chemin de module interne comme API +pas de default method masquant une policy critique sans justification +``` + +### 11.6 Codecs + +`bincode` reste interdit pour les codecs wire KSP. + +Store ne crée pas un second owner de wire officiel : + +```text +wire officiel -> ksp-interface-lib +persistence RAW -> ksp-store-api / ksp-store-lib +``` + +Un format de persistence interne éventuellement binaire ne doit pas être présenté comme un nouveau wire Solana public ni introduit sans besoin réel. + +### 11.7 Idempotence + +La release doit prouver un comportement déterministe sur duplicate/retry. + +Ne pas promettre : + +```text +exactly-once distribué +ordre global total non possédé par la source +lossless pour une catégorie non couverte +``` + +### 11.8 Extensibilité backend + +Si `ksp-store-api` définit un backend contract : + +```text +une crate externe doit pouvoir l'implémenter +sans dépendre de ksp-store-lib +sans connaître PostgreSQL +sans accéder à un module privé +``` + +Un canari d'intégration externe doit le prouver. + +--- + +## 12. Première mission `0.3.1-pre.001` + +### 12.1 Vérifier la base réelle + +Inventorier : + +```text +workspace members +workspace dependencies +surface Core +surface Interface +surface Program API +Transport models publics réellement disponibles +absence actuelle de Store +ROADMAP 0.3.x +``` + +Ne pas supposer qu'un type cité dans un ancien prompt existe encore. + +### 12.2 Relire règles et architecture + +Produire une checklist courte des règles qui conditionnent directement le design Store. + +### 12.3 Auditer kbot3 + +Produire la matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` définie en section 4. + +Le rapport doit au minimum expliquer pourquoi les surfaces N2/N3 historiques ne rentrent pas dans `0.3.1`. + +### 12.4 Auditer PostgreSQL et la crate Rust candidate + +Vérifier version/features actuelles et documenter : + +```text +candidate retenu ou non +features minimales +runtime requirements +migration strategy support +pool/transaction API +error safety +transitive duplicates +``` + +### 12.5 Définir l'inventaire RAW minimal + +Pour chaque catégorie proposée : + +```text +source acquisition +identité logique +payload replayable +provenance +idempotence +queries nécessaires +reason to include now +reason not to defer +``` + +Si le nombre de catégories dépasse le budget de session, réduire avant scaffold. + +### 12.6 Définir l'ownership + +Produire une table : + +```text +concept +owner +public/private +release d'introduction +raison +``` + +Inclure au minimum : + +```text +RAW DTO +persistent reference +write request/outcome +query filter/page +health +backend settings +pool +transaction +migration +notification reference +transport conversion +``` + +### 12.7 Proposer le dependency graph exact + +Cible initiale à confirmer : + +```text +ksp-store-api +└── ksp-core-lib + +ksp-store-lib +├── ksp-store-api +├── ksp-core-lib +├── ksp-logging-lib +└── PostgreSQL dependency +``` + +Justifier toute divergence. + +### 12.8 Proposer l'API candidate + +Donner les signatures candidates essentielles sans les implémenter lourdement. + +Répondre explicitement : + +```text +traits séparés ou façade unique ? +async strategy ? +dyn/object safety réellement requise ? +external backend implementation ? +transaction abstraction publique ou backend privée ? +page cursor opaque ou struct typée ? +``` + +### 12.9 Proposer le schéma PostgreSQL candidat + +Sans l'appliquer encore, fournir : + +```text +tables RAW seulement +colonnes +PK/unique keys +FK seulement si justifiées dans RAW +indexes nécessaires +nullability +bounds/check constraints +migration versioning +``` + +Chaque table doit correspondre à un contrat RAW réellement retenu. + +### 12.10 Threat model + +Couvrir au minimum : + +```text +DSN leak +SQL injection +hostile payload size +duplicate/retry race +partial transaction +schema drift +migration against incompatible existing object +cursor abuse +unbounded query +raw payload error/debug leak +backend error leak +cross-backend contract mismatch +``` + +### 12.11 Stratégie de tests + +Prévoir : + +```text +unit tests module-local +public API canaries +external backend canary +manifest/dependency firewall +schema/migration inventory canary +PostgreSQL integration tests +idempotence/race tests +transaction rollback test +payload/error redaction tests +pagination bounds +release completeness +``` + +Les tests PostgreSQL réels peuvent être `#[ignore]`/opt-in pendant le développement si l'environnement n'est pas toujours disponible, mais un gate PostgreSQL réel doit être planifié avant la réconciliation documentaire finale. + +### 12.12 Sizing et prévision recalibrée + +Chaque tranche intermédiaire vise environ 15–20 minutes de travail effectif. + +Si une tranche dépasse ce budget ou si `0.3.1` ne paraît plus clôturable dans une seule session : + +```text +scinder avant implémentation lourde +mettre à jour le plan +conserver les lanes de fermeture séparées +``` + +### 12.13 Sorties documentaires de `pre.001` + +Créer uniquement ce qui est nécessaire au gate : + +```text +Cargo.toml bump prerelease si exigé par le delta +docs/plans/022-V0_3_1_STORE_RAW_PLAN.md +docs/validation/018-V0_3_1_STORE_RAW.md +deltas/0.3.1/pre.001.md +``` + +Ne pas créer les crates fonctionnelles avant que le gate soit cohérent si le plan décide que le scaffold appartient à `pre.002`. + +### Critères de sortie de `pre.001` + +Le gate est cohérent seulement si : + +```text +base stable v0.2.14 auditée +archive kbot3 auditée +matrice historique produite +versions/dependencies PostgreSQL actuelles auditées +inventaire RAW minimal décidé +hors-scope CORE/DECODE/SPECIALIZED explicite +ownership API/impl/composition fixé +API candidate assez précise pour scaffold +schema candidat RAW-only assez précis pour revue +migration policy candidate documentée +threat model présent +stratégie PostgreSQL live présente +dependency graph exact proposé +prévision souple recalibrée +release encore clôturable dans une session +``` + +Aucun repository PostgreSQL lourd ne commence avant cette sortie. + +--- + +## 13. Prévision souple initiale des prereleases + +Cette prévision est **indicative**. `pre.001` doit la recalibrer selon l'inventaire RAW et l'audit PostgreSQL réel. + +### `pre.001` — Audit KSP + kbot3 + RAW model + PostgreSQL + sizing + +Lecture, matrice historique, ownership, dépendances, API candidate, schema candidat, threat model, stratégie de tests, plan/validation. + +### `pre.002` — Scaffold `ksp-store-api` + `ksp-store-lib` + dependency firewall + +Créer les deux crates, manifests minimaux, façades crate-root et documentation initiale sans schéma fonctionnel lourd. + +### `pre.003` — Contrats RAW backend-agnostic + +Introduire uniquement les types RAW/provenance/références/outcomes réellement retenus par `pre.001`, avec bounds et Debug sûrs. + +### `pre.004` — Capabilities Store API + backend externe canari + +Matérialiser read/write/query contracts nécessaires et prouver qu'un backend externe peut les implémenter sans `ksp-store-lib`. + +### `pre.005` — PostgreSQL runtime foundation + +Settings programmatique, ouverture/pool, error mapping, health minimal, logging KSP et migration runner choisi, sans dépasser RAW. + +### `pre.006` — Schéma/migrations PostgreSQL RAW + +Créer uniquement les tables/constraints/indexes validés par le plan. Aucun objet CORE/DECODE/SPECIALIZED. + +### `pre.007` — Persistence RAW write/idempotence/atomicité + +Implémenter les writes, duplicate/retry semantics et rollback/transaction invariants. + +### `pre.008` — Reads/query/pagination + référence de notification si retenue + +Implémenter les lectures nécessaires, bornes/cursors et uniquement le contrat de notification dont le besoin est démontré. + +### `pre.009` — Adversarial/security/release completeness + +Payload hostile, redaction DSN/error, query bounds, schema drift, duplicate race, dependency/API inventory, absence de scope creep. + +### `pre.010` — Gate technique PostgreSQL final + +Exécuter un PostgreSQL réel sur migrations + write/read/idempotence/rollback et les graphes Cargo finaux. Aucun développement fonctionnel nouveau. + +### `pre.011` — Réconciliation documentaire finale + +README/USAGE, plan, validation, architecture/indexes réellement concernés. Aucun `CHANGELOG.md`, `ROADMAP.md` ni prompt suivant. + +### `pre.012` — Préparation de publication minimale + +Uniquement : + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +prompt de démarrage 0.3.2 +delta pre.012 +``` + +### `rel.001` — Publication stable + +Mécanique de publication uniquement. + +Si l'audit réduit ou augmente le nombre de tranches, préserver l'ordre relatif : + +```text +gate technique PostgreSQL +-> réconciliation documentaire +-> préparation de publication +-> rel.001 +``` + +--- + +## 14. Versionnement, deltas, commits et tags + +Respecter `docs/rules/VERSION_WORKFLOW.md`. + +Exemples : + +```text +livraison pre.001 0.3.1-pre.001 +Cargo 0.3.1-pre.1 +delta deltas/0.3.1/pre.001.md + +livraison fix 0.3.1-pre.003-fix.001 +Cargo si runtime 0.3.1-pre.3.fix.1 + +publication 0.3.1-rel.001 +Cargo stable 0.3.1 +tag stable v0.3.1 +``` + +À partir de `0.1.x`, chaque delta est commité selon le workflow KSP. + +Une archive overlay contient seulement : + +```text +fichiers ajoutés/modifiés de la livraison ++ delta correspondant +``` + +Aucune suppression n'est implicite. + +Le `ROADMAP.md` ne sert pas de changelog de prerelease. Les détails vivent dans le plan/validation/deltas. + +--- + +## 15. Procédure opérateur et validation + +### 15.1 Gate standard Rust/Markdown + +Pour toute prerelease Rust : + +```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.1 +cargo check --workspace +cargo clippy --workspace --all-targets +``` + +Puis tests ciblés de la tranche. + +### 15.2 Gate workspace + +À chaque tranche technique suffisamment complète : + +```bash +cargo test -p ksp-store-api +cargo test -p ksp-store-lib +cargo test --workspace +``` + +### 15.3 Graphes + +Quand les manifests Store existent ou changent : + +```bash +cargo tree -p ksp-store-api --edges normal +cargo tree -p ksp-store-lib --edges normal +cargo tree --duplicates +``` + +Le graphe `ksp-store-api` doit rester backend-agnostic. + +### 15.4 PostgreSQL live/integration + +Avant fermeture technique, exécuter le gate PostgreSQL réel défini par `pre.001`. + +Il doit prouver au minimum pour la surface retenue : + +```text +bootstrap/migrations sur base propre +réouverture sur schema déjà valide +write +read +idempotent duplicate/retry +transaction rollback sur échec +query/page bounds +aucun secret dans diagnostic visible +``` + +Si un test volontairement destructive/schema-management existe, il doit cibler exclusivement un namespace/base de test explicitement provisionné. + +Aucun test ne doit toucher une base opérateur non dédiée par défaut. + +--- + +## 16. Canaris obligatoires + +### 16.1 API publique Store + +Un test d'intégration doit consommer la façade crate-root uniquement. + +### 16.2 External backend + +Une implémentation de test séparée doit satisfaire les contracts publics retenus sans dépendre de `ksp-store-lib` ni de PostgreSQL. + +### 16.3 Dependency firewall + +Verrouiller au minimum : + +```text +ksp-store-api -X-> ksp-store-lib +ksp-store-api -X-> Transport/Program/Materializer +ksp-store-lib -X-> Transport/Program/Materializer/Wallet/Config/Tauri +``` + +### 16.4 RAW-only completeness + +Le release completeness doit détecter l'apparition accidentelle de : + +```text +CoreTransaction +DecodedEvent +MaterializationOutput +SpecializedProjection +Program decoder +worker/job lifecycle +transport client +``` + +ou tout équivalent qui ouvrirait D2/D3/D4. + +### 16.5 PostgreSQL privacy + +Aucun type public de `ksp-store-api` ne doit exposer : + +```text +sqlx::PgPool +PgConnection +Transaction PostgreSQL concrete +nom physique de table +SQL brut +``` + +### 16.6 Security + +Canaris pour : + +```text +DSN redaction +payload hostile Debug/Error +oversize input +unbounded page size +SQL value binding +schema incompatibility +partial write rollback +concurrent duplicate +``` + +### 16.7 Notification + +Si la référence/notification RAW est introduite : + +```text +format indépendant de live/backfill/import +payload compact +aucune donnée source du backlog dupliquée inutilement +publication testée seulement après commit +``` + +Le mécanisme de diffusion reste absent. + +--- + +## 17. Critères de clôture de `0.3.1` + +La release peut être publiée seulement si : + +```text +ksp-store-api existe et reste backend-agnostic +ksp-store-lib existe avec PostgreSQL de référence +surface durable limitée à RAW +inventaire RAW décidé et documenté +persistence replayable pour les catégories couvertes +idempotence/duplicate semantics explicites +migrations RAW-only validées +aucun type PostgreSQL dans Store API +backend externe canari PASS +public API canari PASS +dependency firewall PASS +security/adversarial PASS +PostgreSQL integration gate PASS +cargo test -p ksp-store-api PASS +cargo test -p ksp-store-lib PASS +cargo test --workspace PASS +graphes Cargo inspectés +aucun CORE/DECODE/SPECIALIZED anticipé +aucun Transport/Program/Materializer dependency creep +aucune lecture Config/env directe dans Store +aucun secret/payload brut dans logs/errors/debug +documentation durable réconciliée +CHANGELOG/ROADMAP/prompt 0.3.2 préparés dans la dernière prerelease dédiée +``` + +Une catégorie RAW explicitement reportée par `pre.001` n'est pas un échec si le scope réduit reste cohérent avec `0.3.3` et si le report est tracé. + +Un gate PostgreSQL réel manquant est en revanche bloquant pour déclarer le backend officiel validé. + +--- + +## 18. Release/session suivante envisagée + +Après `0.3.1`, la séquence active prévoit : + +```text +0.3.2 — étendre ksp-interface-lib avec les wires génériques nécessaires aux acquisitions et à la future normalisation CORE +0.3.3 — introduire ksp-job-api + premier backfill historique concret vers RAW +0.3.4 — introduire une application spécialisée de backfill/inspection RAW +``` + +Puis la couche RAW doit être complétée avec le worker/service live et les outils d'exploitation réellement nécessaires avant d'ouvrir CORE. + +`0.3.1` ne doit pas aspirer ces releases pour rendre Store artificiellement « complet ». + +Le prompt suivant préparé en fin de release sera donc consacré à `0.3.2`, sauf décision de roadmap explicitement modifiée avant la clôture. + +--- + +## 19. Instruction d'ouverture + +À l'ouverture de la session `0.3.1` : + +1. vérifier que la base est exactement `v0.2.14` stable ; +2. vérifier que l'archive historique `khadhroony-bot3_v0.5.3-pre.005-fix010.zip` est disponible ; +3. lire les règles et architectures des sections 3.1 et 3.2 ; +4. inventorier l'état réel du workspace et l'absence de Store actuel ; +5. auditer l'ancien `ks-store`, ses contracts RAW et ses migrations ; +6. produire la matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` ; +7. réauditer PostgreSQL et la dépendance Rust candidate avec sources primaires actuelles ; +8. définir l'inventaire RAW minimal, les invariants d'idempotence/provenance et le scope exact de persistence ; +9. proposer ownership, API backend-agnostic, dependency graph, schema PostgreSQL candidat, threat model et stratégie de tests live ; +10. recalibrer la prévision souple et le sizing ; +11. créer seulement ensuite le plan, la validation et le delta `0.3.1-pre.001` ; +12. **ne pas commencer le scaffold fonctionnel lourd ni les migrations PostgreSQL avant que le gate `pre.001` soit cohérent**. + +Le premier message de travail doit commencer par l'audit de la base réelle, des règles et de l'archive historique, pas par un schéma SQL ou une API inventés depuis la mémoire.