From c27428d6c0a1065f55665466ecea08ec9123043f Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Mon, 31 Aug 2026 00:46:52 +0200 Subject: [PATCH] v0.3.4-pre.013 --- CHANGELOG.md | 14 +- Cargo.toml | 4 +- ROADMAP.md | 8 +- deltas/0.3.4/pre.013.md | 283 +++++++ prompts/024-V0_3_5_START_PROMPT.md | 1109 ++++++++++++++++++++++++++++ 5 files changed, 1411 insertions(+), 7 deletions(-) create mode 100644 deltas/0.3.4/pre.013.md create mode 100644 prompts/024-V0_3_5_START_PROMPT.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f531e5..8919500 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,20 @@ - + # 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. diff --git a/Cargo.toml b/Cargo.toml index 9f41352..271fff0 100644 --- a/Cargo.toml +++ b/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" diff --git a/ROADMAP.md b/ROADMAP.md index 4f3f3cb..2ff1ff1 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # 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. diff --git a/deltas/0.3.4/pre.013.md b/deltas/0.3.4/pre.013.md new file mode 100644 index 0000000..5f2e71c --- /dev/null +++ b/deltas/0.3.4/pre.013.md @@ -0,0 +1,283 @@ + + + +# 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. diff --git a/prompts/024-V0_3_5_START_PROMPT.md b/prompts/024-V0_3_5_START_PROMPT.md new file mode 100644 index 0000000..789307d --- /dev/null +++ b/prompts/024-V0_3_5_START_PROMPT.md @@ -0,0 +1,1109 @@ + + + +# Prompt de démarrage `0.3.5` — Interface passive acquisition events + +## 1. Identité de la release et base exacte requise + +La release à ouvrir est : + +```text +0.3.5 — ksp-interface-lib : modèles passifs/event-only réellement partagés +``` + +La base autoritaire attendue est exclusivement la release stable : + +```text +v0.3.4 +workspace.package.version = 0.3.4 +``` + +L'archive/repository `v0.3.4` fourni par l'opérateur prévaut sur toute mémoire, snippet, ancien artefact ou hypothèse de cette session. + +La première tranche est : + +```text +0.3.5-pre.001 +``` + +Elle est obligatoirement une tranche de **lecture + inventaire des consumers/producers + audit sémantique multi-transport + brainstorming + threat model + sizing + planification**. + +Ne pas créer immédiatement une grande enum `Event`, des wrappers de DTO Transport ou des modèles persistants parallèles avant la sortie cohérente de ce gate. + +--- + +## 2. Mission et résultat attendu + +`0.3.5` intervient après la fermeture de la persistence RAW PostgreSQL : + +```text +0.3.1 ksp-store-api : contrats RAW backend-agnostic +0.3.2 Store/PostgreSQL foundation +0.3.3 RawTransaction PostgreSQL +0.3.4 RawAccountState PostgreSQL + RAW 10/10 +0.3.5 Interface : événements passifs réellement partagés +``` + +La mission est d'étendre **`ksp-interface-lib` uniquement lorsque la sémantique d'un événement est réellement commune**, afin que les couches de composition/acquisition futures puissent consommer un contrat KSP passif sans dépendre des DTOs HTTP/WS/gRPC/provider. + +Le résultat attendu n'est **pas** un catalogue exhaustif de tout ce que les transports savent notifier. + +Le résultat attendu est : + +```text +inventaire actuel des surfaces event-like +matrice de convergence sémantique par candidat +ownership Interface/Transport/Store/consumer explicitement décidé +un sous-ensemble minimal de contrats passifs KSP-owned réellement justifiés +aucune duplication des modèles persistants/replayables de ksp-store-api +aucune dépendance Interface -> Transport ou Interface -> Store +aucun event bus, scheduler, worker, job ou persistence +aucun provider DTO promu en contrat transversal +API crate-root stable, bornée et consommable depuis une crate externe +``` + +Une famille candidate **reste reportée** si le gate ne démontre pas simultanément une sémantique commune suffisamment précise et un usage consumer concret/proche qui justifie une API publique durable. + +La release suivante reste : + +```text +0.3.6 — ksp-job-api + premier backfill historique RAW concret +``` + +--- + +## 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 les familles applicables : + +```text +KSP-API-* +KSP-TRANSPORT-* +KSP-STORE-* +KSP-NOTIFY-* +KSP-PROC-* +KSP-REL-* + +DEP-KSP-* +DEP-LOG-* +DEP-STORE-* +DEP-WORKER-* +DEP-JOB-* +``` + +Rappels structurants : + +```text +ksp-interface-lib -> ksp-core-lib +ksp-interface-lib -X-> ksp-program-api +ksp-interface-lib -X-> ksp-program-lib +ksp-interface-lib -X-> ksp-onchain-transport-lib +ksp-interface-lib -X-> ksp-store-api +ksp-interface-lib -X-> ksp-store-lib +ksp-interface-lib -X-> Config/Wallet + +ksp-onchain-transport-lib possède ses DTOs/runtime HTTP/WS/gRPC +ksp-store-api possède les modèles persistants/replayables RAW +composition supérieure convertit entre contrats lorsque nécessaire +``` + +Un fix strictement documentaire ne modifie pas `workspace.package.version`. Une prerelease non-fix, y compris la tranche de publication, synchronise la version Cargo conformément à `VER-ID-009`. + +### 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/008-DATA_MATERIALIZATION_AND_STORE.md +docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md +docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md +``` + +Préserver notamment : + +```text +Interface = contrat passif/wire partagé, pas runtime réseau +Transport = protocoles, sessions, provider DTOs, backpressure/reconnect +Store API = persistence/replay/cursors/outcomes RAW +Store = source de vérité durable du backlog +notification after commit = wake-up non durable, distinct d'un event réseau +worker/job = policy, range, batch, progression, retries opérationnels +``` + +### 3.3 Fondation Interface stable `0.2.13` + +Lire intégralement : + +```text +docs/plans/020-V0_2_13_INTERFACE_PLAN.md +docs/validation/016-V0_2_13_INTERFACE.md +crates/ksp-interface-lib/Cargo.toml +crates/ksp-interface-lib/README.md +crates/ksp-interface-lib/USAGE.md +crates/ksp-interface-lib/src/** +crates/ksp-interface-lib/tests/** +``` + +La base stable possède une petite surface passive Program-facing : + +```text +Pubkey +ProgramAccountMeta +ProgramInstruction +MAX_PROGRAM_INSTRUCTION_ACCOUNTS +MAX_PROGRAM_INSTRUCTION_DATA_LEN +ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED +``` + +Le graphe normal attendu reste actuellement : + +```text +ksp-interface-lib +└── ksp-core-lib +``` + +`0.3.5` peut élargir la responsabilité documentaire de la crate aux événements passifs d'acquisition retenus, mais ne doit pas transformer Interface en transport, en façade Store ou en runtime. + +### 3.4 Contrats RAW/ownership stabilisés `0.3.1` + +Lire : + +```text +docs/plans/022-V0_3_1_STORE_RAW_PLAN.md +docs/validation/018-V0_3_1_STORE_RAW.md +crates/ksp-store-api/Cargo.toml +crates/ksp-store-api/src/** +crates/ksp-store-api/tests/** +``` + +Relire particulièrement les décisions : + +```text +persistent/replayable -> ksp-store-api +event-only partagé -> ksp-interface-lib préférentiel +RawTransaction + RawTransactionObservation restent Store API +RawAccountState + RawAccountObservation restent Store API +logsSubscribe n'a pas créé RawLog persistant +TransactionStatusObservation a été reporté faute de convergence +slot/root/slotsUpdates/vote sont des candidats event-only à réauditer +wake-up « persisted data available » est distinct des events réseau +``` + +Ne pas déplacer ni recopier les types Store pour rendre Interface plus pratique. + +### 3.5 Store/PostgreSQL stable `0.3.2`–`0.3.4` + +Lire au minimum : + +```text +docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md +docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md +docs/plans/025-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT_PLAN.md + +docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md +docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md +docs/validation/021-V0_3_4_STORE_POSTGRES_RAW_ACCOUNT.md + +crates/ksp-store-lib/README.md +crates/ksp-store-lib/USAGE.md +crates/ksp-store-postgres-lib/README.md +crates/ksp-store-postgres-lib/USAGE.md +``` + +L'objectif n'est pas d'auditer de nouveau SQL/migrations, mais de préserver la frontière désormais stable : + +```text +10 capabilities RAW persistantes +6 RawTransaction* +4 RawAccount* +aucune capability de rétention account +aucun event réseau persistant ajouté par défaut +``` + +### 3.6 Surfaces Transport à auditer + +Lire les contrats publics et les tests associés de `ksp-onchain-transport-lib`, en particulier : + +```text +crates/ksp-onchain-transport-lib/src/ws_transactions.rs +crates/ksp-onchain-transport-lib/src/ws_cluster.rs +crates/ksp-onchain-transport-lib/src/ws_accounts.rs +crates/ksp-onchain-transport-lib/src/ws_blocks.rs +crates/ksp-onchain-transport-lib/src/ws_helius_transactions.rs +crates/ksp-onchain-transport-lib/src/grpc_subscribe.rs +crates/ksp-onchain-transport-lib/src/grpc_stream.rs +crates/ksp-onchain-transport-lib/src/rpc_transactions.rs +crates/ksp-onchain-transport-lib/src/rpc_blocks.rs +crates/ksp-onchain-transport-lib/tests/** +``` + +Inventorier au minimum : + +```text +standard WS signatureNotification +standard WS logsNotification +standard WS slotNotification +standard WS rootNotification +standard WS slotsUpdatesNotification +standard WS voteNotification +standard WS account/program notifications +standard WS blockNotification +Helius transaction notifications +Yellowstone Account +Yellowstone Slot +Yellowstone Transaction +Yellowstone TransactionStatus +Yellowstone Block / BlockMeta +Yellowstone Entry +HTTP getSignatureStatuses / getTransaction / getBlock surfaces pertinentes +``` + +Les DTOs ci-dessus sont **Transport-owned**. Ils sont des inputs d'audit, pas des types à réexporter depuis Interface. + +Lire enfin : + +```text +CHANGELOG.md +ROADMAP.md +``` + +Créer en `pre.001` : + +```text +docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md +docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md +``` + +--- + +## 4. Archive historique kbot3 + +L'archive historique kbot3 **n'est pas requise** pour `0.3.5`. + +Raison : la décision à prendre dépend des sémantiques **actuelles** déjà matérialisées dans KSP et des contrats officiels actuels HTTP/WS/Yellowstone. Une ancienne hiérarchie d'events ne doit pas devenir une autorité par inertie. + +Donc : + +```text +ne pas bloquer pre.001 sur khadhroony-bot3_v0.5.3-pre.005-fix010.zip +ne pas inventer un audit historique obligatoire +ne pas recopier une ancienne Event enum si elle est retrouvée +``` + +Si l'opérateur fournit volontairement une archive historique, elle peut être consultée **après** l'inventaire KSP actuel comme source comparative non normative, sans modifier les critères d'admission. + +--- + +## 5. Sources externes normatives à réauditer lorsque la fraîcheur importe + +Cette release dépend davantage de la **sémantique** des notifications que de nouvelles dépendances Cargo. + +Lorsque `pre.001` compare des surfaces, vérifier les sources primaires réellement actuelles pour les opérations concernées : + +```text +Solana JSON-RPC HTTP +Solana WebSocket subscriptions +Yellowstone gRPC / geyser proto actuel utilisé par KSP +Helius LaserStream WebSocket seulement pour ses extensions déjà implémentées +``` + +Comparer la documentation externe avec les types/tests effectivement présents dans `ksp-onchain-transport-lib`. + +Si une différence apparaît : + +```text +ne pas modifier Transport dans 0.3.5 par réflexe +identifier d'abord s'il s'agit d'un bug Transport bloquant ou d'une évolution externe +si correction Transport nécessaire, la traiter dans une tranche/release propriétaire adaptée +ne pas masquer la divergence en élargissant le modèle Interface +``` + +Aucun SDK provider n'est ajouté pour cette release. + +Aucun codec wire (`borsh`, `wincode`, etc.) n'est ajouté uniquement pour représenter un événement passif. `bincode` reste interdit pour les codecs wire KSP. + +--- + +## 6. Ownership à figer avant tout nouveau type + +Pour chaque candidat, `pre.001` doit choisir exactement une catégorie principale. + +### 6.1 Store API + +Un fait appartient à `ksp-store-api` lorsqu'il est : + +```text +persistant +replayable +durablement queryable +partie du backlog ou de l'identité RAW +``` + +Exemples déjà acquis : + +```text +RawTransaction +RawTransactionObservation +RawAccountState +RawAccountObservation +RawPageCursor / queries / outcomes +``` + +`0.3.5` ne duplique pas ces modèles sous un nom `Event`. + +### 6.2 Transport + +Un fait reste Transport lorsqu'il dépend encore : + +```text +d'une méthode HTTP/WS/gRPC spécifique +d'un lifecycle de subscription/session +d'un filter echo provider +d'un format d'erreur provider +d'un payload raw/serde_json forward-compatible +d'un détail Yellowstone/Helius non transversal +``` + +Un type `SolanaLogsNotification`, `YellowstoneSlotUpdate` ou `HeliusTransactionNotification` ne devient pas Interface simplement parce qu'il est public. + +### 6.3 Interface + +Un événement est candidat Interface lorsque : + +```text +il est passif +il n'est pas destiné à devenir une seconde persistence RAW +sa sémantique peut être exprimée sans nom/méthode/provider de transport +au moins deux producteurs/converters ou consumers peuvent raisonnablement partager exactement ce contrat +la conversion ne perd pas une distinction sémantique importante +les champs communs ne sont pas un Option-soup construit par union artificielle +``` + +### 6.4 Composition/pipeline futur + +Une transformation qui nécessite : + +```text +state de session +provenance endpoint/provider +agrégation de plusieurs messages +lookup HTTP supplémentaire +conversion vers RawTransaction/RawAccountState +policy de retry/batch/range +``` + +appartient à une couche de composition/pipeline/worker/job future, pas à la structure passive Interface. + +--- + +## 7. Matrice de candidats obligatoire + +`pre.001` doit produire une matrice par **nature de fait**, pas par nom de méthode. + +### 7.1 Slot / root / lifecycle + +Comparer au minimum : + +```text +WS slotNotification +WS rootNotification +WS slotsUpdatesNotification +Yellowstone Slot update +``` + +Auditer : + +```text +slot +parent +root +status/lifecycle +processed/confirmed/finalized +first shred/completed/created bank/dead +server timestamp +unknown variants +dead error +``` + +Ne pas supposer que `root == finalized`, que `slotNotification` et `slotsUpdates` sont équivalents, ni que tous les statuts Yellowstone possèdent un équivalent WebSocket. + +Une abstraction peut être plus petite que l'union des surfaces si cette petite sémantique est réellement utile et lossless pour le consumer visé. + +### 7.2 Logs realtime + +Comparer : + +```text +WS logsNotification +transaction logMessages présents dans les transactions complètes +Yellowstone Transaction meta/log messages lorsque disponibles +``` + +Préserver la décision déjà acquise : + +```text +logMessages d'une transaction persistée restent dans RawTransaction/STRUCTURAL futur +logsSubscribe peut être un event-only séparé +aucune table RawLog par défaut +``` + +Décider si un event passif de logs possède un vrai consumer distinct du pipeline de transaction complète. + +Ne pas faire entrer `serde_json::Value` provider comme erreur canonique Interface sans justification forte. + +### 7.3 Transaction status + +Comparer : + +```text +HTTP getSignatureStatuses snapshot +WS signatureNotification one-shot/transition +Yellowstone TransactionStatus update +Helius transaction status/notification si réellement applicable +``` + +La décision `0.3.1` est **REPORTÉ** faute de convergence. + +`0.3.5` ne l'annule que si l'audit démontre une nature de fait commune sans perte. + +Ne pas créer : + +```text +TransactionStatusEvent avec une dizaine d'Option pour couvrir toutes les sources +champ status qui mélange received/processed/confirmed/finalized arbitrairement +opaque provider error promue telle quelle +``` + +### 7.4 Vote + +Comparer : + +```text +WS voteNotification +Yellowstone transactions de vote / filtres is_vote +autres surfaces réellement disponibles +``` + +Une transaction marquée `is_vote=true` n'est pas automatiquement équivalente au contenu sémantique d'un `voteNotification` gossip. + +### 7.5 Account / program + +Les notifications account/program peuvent alimenter `RawAccountState`, mais `0.3.5` ne doit pas créer un doublon Interface de : + +```text +RawAccountState +RawAccountStateReference +RawAccountObservation +``` + +Un contrat event-only distinct n'est recevable que si un consumer a besoin d'une sémantique non persistante réellement différente. + +### 7.6 Transaction complète / block + +Les notifications transaction/block servent déjà d'acquisition potentielle de `RawTransaction`. + +Ne pas créer par réflexe : + +```text +InterfaceRawTransaction +TransactionEvent contenant une copie de RawTransaction +RawBlock parallèle +``` + +`RawBlock` reste conditionnel selon le roadmap. + +### 7.7 Yellowstone Entry + +La décision actuelle reste : + +```text +REJET ACTUEL +``` + +Ne rouvrir que si `pre.001` identifie un consumer réel et une destination sémantique claire. La simple disponibilité du proto n'est pas un besoin KSP. + +### 7.8 Notification after commit + +Le wake-up : + +```text +persist +commit +notify +``` + +est **distinct** des événements réseau. + +Son format canonique appartient conceptuellement au domaine Store/API selon `KSP-NOTIFY-*`, mais ne doit pas être matérialisé dans `0.3.5` sans publisher + consumer réel. + +Ne pas l'ajouter à Interface pour « avoir un event générique ». + +--- + +## 8. Contrat de design des types Interface retenus + +Pour chaque type admis par `pre.001` : + +### 8.1 KSP-owned et provider-neutral + +Le nom/type public ne doit pas contenir : + +```text +Yellowstone +Helius +Rpc +WebSocket +Grpc +provider name +subscription id +endpoint id +``` + +sauf si le type décrit explicitement un wire protocolaire possédé par Interface, ce qui n'est pas l'objectif par défaut de cette release. + +### 8.2 Champs privés et API explicite + +Préférer : + +```text +private fields +constructeur(s) validants si admission nécessaire +accessors explicites +#[must_use] approprié +``` + +Les enums publiques évolutives sont `#[non_exhaustive]` lorsque l'ajout de variantes futures est un scénario normal. + +### 8.3 Pas d'Option-soup + +Si deux producers partagent seulement une petite intersection utile, modéliser cette intersection ou deux faits distincts. + +Ne pas créer une structure unique avec des champs optionnels simplement parce que « certains transports les ont ». + +### 8.4 Bornes + +Toute donnée variable hostile doit être bornée si elle entre dans le contrat Interface : + +```text +Vec +String +opaque bytes +liste de slots/logs +error text éventuel +``` + +Les bornes sont des **admission guards Interface**, pas des affirmations de maxima protocolaire. + +### 8.5 Debug et erreurs + +Le `Debug` public ne doit pas dumper : + +```text +logs arbitraires complets +opaque error payloads +raw JSON +payloads provider +listes pathologiques +``` + +Les erreurs utilisent les types Core et des codes/contexte sûrs. + +Ne jamais recopier le payload hostile dans `message` ou `context`. + +### 8.6 Clone/Copy + +Ne dériver `Copy` que pour les petits contrats réellement copiables. + +Ne pas dériver `Clone` sur un événement volumineux simplement par habitude si cela encourage des duplications de payloads importants. + +### 8.7 Sérialisation/codecs + +Par défaut : + +```text +serde absent +serde_json absent +borsh absent +wincode absent +bincode interdit +``` + +N'ajouter un codec/serde que si un **consumer concret de cette release** exige un format public et que l'ownership Interface est démontré. + +### 8.8 Logging + +Des modèles passifs n'ont pas besoin de logging runtime. + +Donc, par défaut : + +```text +ksp-logging-lib absent +constants.rs absent +TRACING_TARGET absent +``` + +Si un comportement runtime est introduit, réauditer d'abord l'ownership : il est probablement hors scope Interface. + +--- + +## 9. Dépendances et frontières interdites + +La cible préférée reste : + +```text +ksp-interface-lib +└── ksp-core-lib +``` + +Toute nouvelle dépendance normale doit être justifiée par `pre.001`. + +Interdictions de release : + +```text +ksp-interface-lib -> ksp-onchain-transport-lib +ksp-interface-lib -> ksp-store-api +ksp-interface-lib -> ksp-store-lib +ksp-interface-lib -> ksp-config-lib +ksp-interface-lib -> ksp-program-api +ksp-interface-lib -> ksp-wallet-lib +ksp-interface-lib -> Tauri +``` + +`ksp-onchain-transport-lib` n'est pas modifié uniquement pour adopter les nouveaux types. Les conversions vers Interface appartiendront au consumer/composition owner lorsque celui-ci est matérialisé, sauf décision architecturale explicitement réauditée dans une release propriétaire. + +Aucune `ksp-interface-api` séparée n'est créée sans contrainte de graphe réelle. + +--- + +## 10. Décisions acquises et questions réellement ouvertes + +### 10.1 Acquis + +```text +Interface possède les contrats passifs/wire réellement partagés +Store API possède les modèles persistants/replayables +Transport possède ses DTOs protocol/provider et lifecycle réseau +pas de RawLog Store par défaut +TransactionStatusObservation reste différé tant que les sémantiques divergent +slot/root/slotsUpdates/vote restent candidats, pas engagements +wake-up post-commit != event réseau +pas de codec générique par anticipation +pas de bincode wire +pas de runtime logging dans un modèle passif +``` + +### 10.2 À décider dans `pre.001` + +Décider explicitement : + +```text +quels consumers concrets justifient 0.3.5 +quelles natures de fait ont >= 2 surfaces réellement convergentes +quels candidats restent Transport-only +quels candidats restent reportés +quels types exacts Interface créer +noms exacts sans provider/protocol leakage +champs exacts et optionality +bornes d'admission +Debug/error policy +Clone/Copy policy +besoin réel ou absence de serde/codec +inventaire crate-root final +si README Interface doit élargir sa description Program-only +si une architecture durable contient une formulation devenue fausse +``` + +Si aucun candidat ne franchit le gate, ne pas fabriquer une API vide ou artificielle pour respecter le numéro de release : documenter le résultat, recalibrer la release et préserver la trajectoire. + +--- + +## 11. Threat model obligatoire + +Couvrir au minimum : + +```text +union artificielle de sémantiques différentes +perte d'un état important lors d'une conversion +Option-soup rendant une source indiscernable +provider/protocol leakage dans une API transversale +duplication de RawTransaction/RawAccountState +promotion d'un snapshot HTTP en event de transition +confusion root/finalized/confirmed/processed +confusion vote gossip / transaction de vote +raw JSON ou error text hostile dans Interface +log/event non borné +Debug volumineux ou sensible +derive Clone pathologique sur gros payload +unknown future variant traité comme sémantique connue +ajout d'un codec sans consumer +nouvelle dépendance Transport/Store inverse +création d'un event bus ou scheduler dans Interface +wake-up post-commit confondu avec event réseau +API fermée impossible à faire évoluer +``` + +--- + +## 12. Première mission `pre.001` + +### 12.1 Vérifier la base + +Avant toute modification fonctionnelle : + +1. vérifier `v0.3.4` stable et `workspace.package.version = 0.3.4` ; +2. lire les règles/architectures listées ci-dessus ; +3. confirmer la surface publique et le graphe actuel de `ksp-interface-lib` ; +4. confirmer la surface RAW Store stable 10/10 ; +5. inventorier toutes les surfaces event-like Transport actuelles ; +6. identifier les consumers actuels et les consumers RAW imminents déjà prévus par l'architecture ; +7. ne pas attendre une archive kbot3. + +### 12.2 Matrice producer -> nature de fait + +Pour chaque surface : + +```text +producer/protocol +méthode/update +nature du fait +champs obligatoires +champs optionnels +ordre/lifecycle +timestamp semantics +error semantics +filter/session/provider metadata +payload volumineux éventuel +persistant/replayable ou event-only +``` + +### 12.3 Matrice de convergence + +Pour chaque nature de fait candidate : + +```text +sources comparées +intersection sémantique exacte +différences non représentables +conversion lossless possible ? +consumer concret +owner retenu +Interface candidate / Transport-only / Store / Reporté / Rejeté +``` + +### 12.4 Matrice anti-duplication Store + +Comparer tout type candidat avec : + +```text +RawTransaction* +RawAccount* +RawAcquisitionProvenance +RawTimestamp +RawContentHash +RawObservationKey +``` + +Démontrer qu'un nouveau contrat Interface ne crée pas une deuxième vérité persistante. + +### 12.5 API sketch + +Pour chaque candidat admis, proposer avant code : + +```text +nom public +struct/enum +champs privés +constructeur/accessors +bounds +Debug +Clone/Copy +non_exhaustive +error code éventuel +``` + +### 12.6 Graphe + +Produire le graphe normal visé de `ksp-interface-lib` et justifier toute différence avec Core-only. + +### 12.7 Threat model + +Produire la matrice de la section 11 avec mitigation/gate associé. + +### 12.8 Sizing + +Chaque tranche prévue au-delà d'environ **15 à 20 minutes de travail effectif** doit être scindée. + +Si plusieurs familles d'events sont admises, les séparer par responsabilité au lieu de créer une grosse tranche « events ». + +Ne jamais aspirer `0.3.6` Job API/backfill dans `0.3.5`. + +### 12.9 Documents de gate + +Créer : + +```text +docs/plans/026-V0_3_5_INTERFACE_ACQUISITION_EVENTS_PLAN.md +docs/validation/022-V0_3_5_INTERFACE_ACQUISITION_EVENTS.md +``` + +### 12.10 Critères de sortie de `pre.001` + +`pre.001` est terminé seulement si : + +```text +base v0.3.4 vérifiée +règles/architecture relues +surface Interface actuelle inventoriée +surface Store 10/10 confirmée et protégée +surfaces HTTP/WS/Yellowstone/Helius pertinentes inventoriées +consumers concrets/imminents identifiés +matrice producer -> nature de fait produite +matrice de convergence produite +ownership de chaque candidat décidé +candidats reportés/rejetés explicités +anti-duplication Store démontrée +API sketch des seuls types retenus produit +bounds/Debug/Clone/non_exhaustive décidés +graphe cible décidé +threat model complet +plan 026 créé +validation 022 créée +prévision souple recalibrée +aucune grosse Event enum ni dépendance runtime ajoutée prématurément +``` + +--- + +## 13. Prévision souple initiale des prereleases + +Cette prévision est volontairement conditionnelle au nombre réel de familles admises par `pre.001`. + +### `pre.001` — Audit consumers, sémantiques et ownership + +Lectures, inventaire Transport/Store/Interface, matrice de convergence, threat model, API sketch, sizing, plan/validation. + +### `pre.002` — Première famille passive retenue + +Implémenter la première nature de fait réellement admise, avec types KSP-owned, bounds, `Debug`, tests unitaires et crate-root minimal. Si aucun candidat n'est admis, recalibrer au lieu d'inventer ce lot. + +### `pre.003` — Famille passive supplémentaire si justifiée + +Ajouter uniquement une seconde famille dont la convergence et le consumer sont déjà prouvés. Si plusieurs familles dépassent le budget, insérer autant de tranches bornées que nécessaire. Si aucune seconde famille n'est justifiée, cette responsabilité est omise/décalée sans remplissage artificiel. + +### `pre.004` — Surface publique, consumer externe et anti-duplication + +Verrouiller exports/modules, consumabilité depuis une crate externe, enums évolutives, absence de Store/Transport leakage et canaris contre la duplication des modèles persistants. + +### `pre.005` — Hardening/completeness Interface + +Hostile inputs/bounds/Debug, dépendances exactes, absence de serde/codec/logging/runtime non justifiés, inventaire des candidats reportés et non-régression Program instruction foundation. + +### `pre.006` — Gate technique final + +```text +cargo fmt/audits +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-interface-lib +cargo test --workspace +cargo tree -p ksp-interface-lib --edges normal +cargo tree -p ksp-interface-lib -e features +cargo tree --duplicates +``` + +Aucun smoke réseau n'est requis par défaut puisque `0.3.5` ne modifie pas le moteur Transport. Si `pre.001` démontre qu'un live est indispensable pour établir une sémantique, créer un gate technique séparé avant la réconciliation documentaire. + +### `pre.007` — Réconciliation documentaire finale + +README/USAGE Interface, plan `026`, validation `022` et architecture/références réellement devenues fausses. `USAGE.md` reste version-neutre. Ne pas toucher `CHANGELOG.md`, `ROADMAP.md` ni au prompt suivant. + +### `pre.008` — Préparation de publication minimale + +Uniquement : + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +prompts/025-V0_3_6_START_PROMPT.md +deltas/0.3.5/pre.008.md +``` + +Le numéro réel peut dériver si `pre.001` insère/retire des lots ; les responsabilités de fermeture restent dans cet ordre. + +### `rel.001` — Publication stable + +Version finale + delta uniquement. + +--- + +## 14. Versionnement, deltas, commits et tags + +Respecter `docs/rules/VERSION_WORKFLOW.md`. + +Rappels : + +```text +workspace.package.version prerelease : 0.3.5-pre.N +livraison : 0.3.5-pre.NNN +fix code/runtime/config : Cargo 0.3.5-pre.N.fix.M +fix strictement documentaire : Cargo inchangé +prerelease non-fix documentaire/publication : Cargo synchronisé +chaque delta commité +tag stable final : v0.3.5 +``` + +Chaque delta contient au minimum : + +```text +base requise +objectif +fichiers ajoutés +fichiers modifiés +fichiers supprimés +validations exécutées +validations non exécutées +décisions +questions ouvertes +``` + +Une commande non exécutée n'est jamais déclarée PASS. + +--- + +## 15. Procédure d'application et validation opérateur + +Après chaque overlay : + +```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.5 +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-interface-lib +``` + +Lorsque la surface publique change : + +```bash +cargo test -p ksp-program-api +``` + +pour vérifier la non-régression du consumer Program existant, sans obliger Program API à utiliser les nouveaux events. + +Au gate technique final : + +```bash +cargo test --workspace +cargo tree -p ksp-interface-lib --edges normal +cargo tree -p ksp-interface-lib -e features +cargo tree --duplicates +``` + +Ne pas ajouter de build Tauri ou de smoke réseau sans changement correspondant réellement à leur responsabilité. + +--- + +## 16. Critères de clôture de `0.3.5` + +La release stable est prête seulement si : + +```text +les types ajoutés correspondent à des faits réellement partagés +chaque candidat refusé/reporté reste documenté +aucun modèle persistent/replayable Store n'est dupliqué +aucun DTO provider/Transport n'est réexporté +ksp-interface-lib ne dépend ni de Transport ni de Store +le graphe de dépendances reste minimal et justifié +aucun event bus/scheduler/runtime n'est introduit +aucun codec/serde/logging n'est ajouté sans consumer réel +les types variables sont bornés +Debug/errors restent sûrs et bornés +les enums publiques évolutives sont ouvertes de manière appropriée +la foundation ProgramInstruction reste non régressée +une crate externe peut consommer les nouveaux contrats depuis le crate-root +workspace/Clippy/tests/graphes sont verts +README/USAGE/plan/validation sont réconciliés selon leur rôle +prompt 0.3.6 est prêt +``` + +Il n'existe **aucun quota minimal d'events à créer**. La qualité de la frontière prime sur le nombre de types. + +--- + +## 17. Hors périmètre explicite + +Ne pas ouvrir dans `0.3.5` : + +```text +modification fonctionnelle de ksp-onchain-transport-lib +nouvelle persistence Store +nouvelle migration PostgreSQL +RawLog table +RawBlock sans besoin démontré +RawTransaction / RawAccountState bis dans Interface +notification bus/runtime +PostgreSQL LISTEN/NOTIFY +Redis/Kafka/NATS +ksp-worker-api +worker RAW live +ksp-job-api +backfill 0.3.6 +Store Desk / app backfill 0.3.7 +STRUCTURAL persistence +Program decoder/materializer +execution +provider SDK +codec wire générique +``` + +--- + +## 18. Release suivante et instruction d'ouverture + +La release suivante envisagée est : + +```text +0.3.6 — Job API + premier backfill historique RAW +``` + +### Instruction d'ouverture + +À réception de la base stable `v0.3.4` : + +1. vérifier la base exacte et le graphe actuel de `ksp-interface-lib` ; +2. lire règles, architecture, foundation Interface et décisions Store RAW `0.3.1`–`0.3.4` ; +3. inventorier les surfaces event-like actuelles de `ksp-onchain-transport-lib` ; +4. réauditer les docs officielles HTTP/WS/Yellowstone uniquement pour les candidats réellement comparés ; +5. identifier les consumers et produire les matrices producer/nature de fait/convergence/ownership ; +6. préserver `RawTransaction`/`RawAccountState` comme vérité persistante Store API ; +7. figer seulement les types passifs Interface dont la sémantique et l'usage sont démontrés ; +8. produire threat model, sizing, plan `026` et validation `022` ; +9. **ne pas attendre l'archive kbot3 : elle n'est pas requise pour cette release** ; +10. **ne pas commencer Job API/backfill, worker live, Store notifications ou modifications Transport avant la clôture cohérente de `0.3.5-pre.001`**.