diff --git a/CHANGELOG.md b/CHANGELOG.md index e96cb45..a0a92a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,16 @@ - + # Changelog KSP +## 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`. + +La dependency direction finale reste strictement `ksp-interface-lib -> ksp-core-lib -> solana-pubkey`. Aucun `serde`, codec générique (`borsh`, `wincode`, `bincode`), `solana-instruction`, runtime réseau ou logging n’est ajouté à cette foundation. Les canaris public API, consumer externe, dependency firewall et release completeness verrouillent les six exports crate-root, les quatre modules de production, l’absence de narrowing/codec caché, le transfert des `Vec` admis sans réallocation interne et la non-répétition de matériel hostile dans les erreurs. `pre.005-fix.001` corrige uniquement un faux positif du scanner Logging provoqué par le littéral de test `tracing::`, sans changement de production ni de dépendance. Les gates `pre.006` et `pre.007` passent ensuite audits Rust/Markdown, `cargo check`, Clippy, tests Interface, ownership Logging, workspace complet et graphes Cargo avant la réconciliation documentaire finale. + +`prompts/019-V0_2_14_START_PROMPT.md` ouvre `0.2.14 — Program API foundation` exclusivement depuis le tag stable `v0.2.13`. Le gate `pre.001` de cette prochaine release exige aussi l’archive historique `khadhroony-bot3_v0.5.3-pre.005-fix010.zip` afin d’auditer les anciens contrats decoder/executor sous une matrice `REPRENDRE / REDESSINER / REPORTER / REJETER`, sans faire de kbot3 une autorité architecturale ni recréer son monolithe `ks-lib`. + ## 0.2.12 — SOL Prices Desk + projection prix Wallet — 2026-08-27 `0.2.12` ajoute `ksp-app-solprices-desk`, troisième Desk Tauri spécialisé de KSP, comme HID strictement provider-neutral au-dessus de `ksp-offchain-transport-lib`. Son composite dédié sélectionne `std.logging` et `std.offchain_transport`; la vue Prices expose l’inventaire des huit providers SOL/USD, disponibilité, sémantique, auth, prix exact sous forme de chaîne, timestamps provider/KSP distincts et retry deadline sans inventer de fraîcheur. Les refresh manuel individuel, sélectionné et global passent exclusivement par `MarketPriceService`; les batchs sont bornés à `1..=64`, les états `in_flight` restent backend-owned et aucun polling, scheduler, fallback, moyenne ou prix canonique n’est introduit dans le Desk. Le frontend conserve l’absence de réseau/persistence navigateur et journalise les interactions sans prix, credential, URL, header ou payload provider. diff --git a/Cargo.toml b/Cargo.toml index 2afba0b..ef3f171 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 310 +# version: 311 [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-wallet-lib"] [workspace.package] -version = "0.2.13-pre.7" +version = "0.2.13-pre.8" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index 772c9c7..a5dbfe2 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,5 @@ - + # Roadmap KSP @@ -57,8 +57,8 @@ Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues. U - [X] `0.2.10` — OrbitFlare Yellowstone gRPC stable : profil Config V3 Devnet, License Key injectée comme metadata secrète `x-token`, smoke live `Subscribe -> Slot + Ping` validé deux fois, sans modification du moteur N1/N2 ni heartbeat provider. - [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. -- [ ] `0.2.13` — Introduire la première surface de `ksp-interface-lib`, façade wire KSP publique et passive utilisable par les implémentations officielles et externes ; `pre.001` doit confronter l’architecture actuelle aux contrats utiles de l’ancien `khadhroony-bot3` sans recréer son monolithe `ks-lib`, et séparer explicitement données wire, comportement Program et implémentations. -- [ ] `0.2.14` — Introduire `ksp-program-api` comme premier contrat Program extensible, sans imposer encore `ksp-program-lib` complet ; les traits de reconnaissance/decode/build et autres comportements ne doivent pas être aspirés prématurément dans `ksp-interface-lib`. +- [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. ### TODO/IDEAS — providers Yellowstone non planifiés diff --git a/deltas/0.2.13/pre.008.md b/deltas/0.2.13/pre.008.md new file mode 100644 index 0000000..6d05e02 --- /dev/null +++ b/deltas/0.2.13/pre.008.md @@ -0,0 +1,233 @@ + + + +# Delta `0.2.13-pre.008` — préparation minimale de publication + +## 1. Base + +```text +0.2.13-pre.007 +``` + +Le gate opérateur de `pre.007`, exécuté le **28 août 2026**, est intégralement vert : + +```text +cargo fmt --all PASS +audits Rust / export completeness / workspace PASS +audit Markdown PASS — 164 tables / 120 fichiers +cargo check --workspace PASS +cargo clippy --workspace --all-targets PASS +cargo test -p ksp-interface-lib PASS +cargo test --workspace PASS +``` + +La réconciliation documentaire finale est donc fermée avant cette tranche. + +## 2. Objectif + +`pre.008` est exclusivement la lane minimale de préparation de publication de `0.2.13` imposée par `VER-LIFECYCLE-003` et `PROMPT_STRUCTURE.md`. + +Elle ne rouvre aucun code, test, README/USAGE, plan, validation, architecture, règle ou configuration. + +Elle : + +```text +bump la prerelease Cargo vers pre.8 +prépare l'entrée CHANGELOG stable 0.2.13 +synchronise le statut global ROADMAP +ajoute le prompt autonome 0.2.14 +trace cette préparation dans le delta +``` + +## 3. Version technique + +```text +0.2.13-pre.7 +-> +0.2.13-pre.8 +``` + +Le bump est mécanique pour une prerelease non-fix. + +## 4. Changelog / Roadmap + +`CHANGELOG.md` prépare l'entrée stable : + +```text +0.2.13 — Interface / wire foundation — 2026-08-28 +``` + +Le résumé conserve les faits de clôture réellement prouvés : + +```text +ProgramAccountMeta + ProgramInstruction passifs +255 account metas / 10_240 bytes +Error/Debug sans payload hostile +graphe Interface -> Core uniquement +aucun serde/codec générique/solana-instruction/network/logging +canaris public API / external consumer / dependency firewall / completeness +pre.005-fix.001 limité au faux positif scanner Logging +gates techniques et documentaires finaux verts +``` + +`ROADMAP.md` marque `0.2.13` comme terminé et maintient `0.2.14` comme prochaine release active. + +## 5. Prompt `0.2.14` + +Ajout : + +```text +prompts/019-V0_2_14_START_PROMPT.md +``` + +Le prompt ouvre : + +```text +0.2.14 — Program API foundation +``` + +exclusivement depuis : + +```text +v0.2.13 +``` + +Le démarrage exige explicitement **deux archives** : + +```text +archive opérateur KSP v0.2.13 +khadhroony-bot3_v0.5.3-pre.005-fix010.zip +``` + +Ordre d'autorité fixé : + +```text +v0.2.13 + règles/architecture KSP autorité actuelle +kbot3 historique audit/héritage uniquement +``` + +L'archive kbot3 est obligatoire pour le gate `pre.001` afin d'auditer réellement les anciens contrats : + +```text +ks-lib/src/decoder/api/contracts.rs +ks-lib/src/decoder/api/decoder.rs +ks-lib/src/model/decoded.rs +ks-lib/src/model/replay.rs +ks-lib/src/model/solana.rs +ks-lib/src/executor/api/execution.rs +ks-lib/src/executor/api/executor.rs +``` + +Le prompt impose la matrice : + +```text +REPRENDRE +REDESSINER +REPORTER +REJETER +``` + +et protège notamment les frontières : + +```text +Core = Pubkey / Program IDs / Error +Interface = wire passif +Program API = comportements/contracts extensibles +Program Lib = implémentations officielles futures +CORE futur = replay/context transaction/CPI/logs/return data/balance deltas +Execution futur = policy/wallet/network/simulation/send/confirmation +``` + +La prévision souple initiale réserve distinctement audit/sizing, scaffold, contracts, hardening, gate technique, réconciliation documentaire et préparation de publication. + +## 6. Fichiers ajoutés/modifiés + +Ajoutés : + +```text +prompts/019-V0_2_14_START_PROMPT.md +deltas/0.2.13/pre.008.md +``` + +Modifiés : + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +``` + +Aucun fichier supprimé. + +## 7. Surfaces volontairement inchangées + +Cette tranche ne touche pas : + +```text +README.md +RULES.md +.env.example +config/** +crates/** +docs/** +prompts/001..018 +``` + +En particulier : + +```text +crates/ksp-interface-lib/src/** +crates/ksp-interface-lib/tests/** +crates/ksp-interface-lib/unit_tests/** +crates/ksp-interface-lib/README.md +crates/ksp-interface-lib/USAGE.md +docs/plans/020-V0_2_13_INTERFACE_PLAN.md +docs/validation/016-V0_2_13_INTERFACE.md +docs/architecture/** +``` + +## 8. Validations de préparation + +À exécuter dans l'environnement de préparation : + +```text +audit Rust workspace +audit Markdown +contrôle exact du payload overlay +contrôle des versions/file headers +``` + +Aucun résultat Cargo nouveau n'est revendiqué tant qu'il n'a pas été exécuté par l'opérateur sur `pre.008`. + +## 9. 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.13 +cargo check --workspace +cargo clippy --workspace --all-targets +cargo test -p ksp-interface-lib +cargo test --workspace +``` + +Aucun smoke réseau/live ni nouveau graphe Cargo n'est requis puisque cette lane ne modifie ni code ni dépendances. + +## 10. Suite + +Si le gate est vert : + +```text +0.2.13-rel.001 +``` + +La release finale effectue uniquement la mécanique de publication stable : + +```text +workspace.package.version = 0.2.13 +delta rel.001 +commit de publication +tag stable v0.2.13 après validation opérateur +``` + +`rel.001` ne doit contenir aucun rattrapage fonctionnel ou documentaire. diff --git a/prompts/019-V0_2_14_START_PROMPT.md b/prompts/019-V0_2_14_START_PROMPT.md new file mode 100644 index 0000000..d9efceb --- /dev/null +++ b/prompts/019-V0_2_14_START_PROMPT.md @@ -0,0 +1,1430 @@ + + + +# Prompt de démarrage `0.2.14` — Program API foundation + +## 1. Identité de la release et bases exactes requises + +La base KSP attendue est **exclusivement** la release stable : + +```text +v0.2.13 +``` + +La release à ouvrir est : + +```text +0.2.14 — Program API foundation +``` + +La première tranche est : + +```text +0.2.14-pre.001 +``` + +Deux archives sont requises au démarrage de la session : + +```text +1. archive opérateur correspondant exactement à KSP v0.2.13 +2. archive historique khadhroony-bot3_v0.5.3-pre.005-fix010.zip +``` + +Ordre d'autorité : + +```text +v0.2.13 réelle / archive opérateur autorité KSP actuelle +règles + architecture de v0.2.13 autorité normative et architecturale +khadhroony-bot3 historique source d'audit/héritage uniquement +anciens prompts / snippets / mémoire auxiliaires seulement +``` + +L'archive kbot3 **n'est pas facultative pour le gate `pre.001`** : cette release porte précisément le premier contrat Program extensible de KSP et doit confronter l'architecture actuelle aux anciens contrats de decoder/executor avant de figer une nouvelle API. Si l'archive historique n'est pas disponible, ne pas inventer son contenu depuis la mémoire et ne pas déclarer l'audit d'héritage terminé. + +Ne pas ouvrir `0.2.14` depuis : + +```text +0.2.13-pre.* +0.2.13-pre.*-fix.* +0.2.13-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 +``` + +Si une divergence existe entre le prompt et la base stable réelle, la base réelle gagne et la divergence devient une sortie explicite de l'audit `pre.001`. + +À l'ouverture, vérifier au minimum : + +```text +tag Git v0.2.13 si metadata Git disponible +workspace.package.version = 0.2.13 +deltas/0.2.13/rel.001.md présent +prompts/019-V0_2_14_START_PROMPT.md présent +ksp-interface-lib présent et conforme à la surface stable 0.2.13 +ksp-program-api absent sauf contradiction de la base réelle +ksp-program-lib absent sauf contradiction de la base réelle +archive khadhroony-bot3_v0.5.3-pre.005-fix010.zip disponible pour l'audit historique +``` + +`pre.001` est obligatoirement une tranche **lecture + audit KSP actuel + audit kbot3 + brainstorming + frontières + threat/API model + dependency graph + stratégie d'extension externe + sizing + planification**. + +Aucun trait Program définitif, registry runtime, decoder concret ni execution preparer concret ne doit être implémenté avant la sortie cohérente de ce gate. + +--- + +## 2. Mission et résultat attendu + +La mission de `0.2.14` est d'introduire `ksp-program-api` comme **premier contrat public extensible du domaine Program**. + +La crate est une crate `*-api` au sens KSP : + +```text +contrats publics +traits/capabilities/descriptors +surface implémentable depuis une crate externe +pas d'implémentation officielle de protocoles +pas de runtime réseau +pas de persistence +pas de policy produit +``` + +La release doit réaliser la frontière : + +```text +ksp-interface-lib + = wire passif officiel + +ksp-program-api + = comportement Program ouvert / extensible + +ksp-program-lib + = implémentations officielles futures, hors 0.2.14 +``` + +Le résultat attendu à la clôture, sous réserve du sizing et des décisions de `pre.001`, est une foundation suffisamment petite pour être stable et suffisamment réelle pour qu'une crate externe puisse démontrer une implémentation Program sans modifier une enum centrale KSP. + +Les contrats candidats à auditer sont notamment : + +```text +identité d'implémentation Program +capabilities déclarées +reconnaissance déterministe d'une instruction +contrat de decoder instruction +statuts/outcomes/diagnostics minimaux +descriptor de couverture ou surface supportée +registry/composition extensible si une API commune est réellement nécessaire +ProgramExecutionPreparer et PreparedProgramExecution uniquement si le sizing démontre que leur foundation appartient déjà à 0.2.14 +``` + +La release **ne doit pas** résoudre artificiellement les contrats qui appartiennent à des couches encore absentes, notamment le replay CORE complet, la persistence D3, les materializers, la policy d'exécution ou l'orchestration transactionnelle. + +La question centrale de `0.2.14` est : + +> quel est le plus petit contrat Program public, ouvert et objectivement réutilisable qui permet de séparer reconnaissance/décodage/préparation du wire Interface, sans recréer les modèles CORE/Store/Execution avant leurs releases ? + +--- + +## 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-NAME-002..003 +KSP-API-001..007 +KSP-PROGRAM-001..006 +DEP-LOG-005 +DEP-PROGRAM-001..004 +DEP-WIRE-001..007 +DEP-PIPE-007..008 +DEP-SOL-001..006 +DEP-PROTO-001..005 +DEP-CARGO-001..007 +``` + +Rappels directement structurants : + +```text +ksp-program-api porte volontairement le suffixe -api et non -lib +une crate *-api est principalement déclarative +une API publique extensible doit être implémentable depuis une crate séparée +les signatures publiques utilisent des types KSP publics stables +pas de pub mod comme raccourci de façade +surface publique réexportée explicitement depuis crate root +Error/Result communs restent possédés par ksp-core-lib +les crates *-api purement déclaratives n'ajoutent pas de logging sans comportement réel +``` + +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.2.14 +``` + +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 +``` + +`docs/architecture/006-WIRE_AND_PROGRAM.md` est la référence centrale de la release. + +Préserver notamment : + +```text +ksp-interface-lib = wire officiel, passif +ksp-program-api = contrats publics ouverts +ksp-program-lib = implémentations officielles ultérieures +extension externe ksp-program--lib possible sans dépendre de ksp-program-lib +pas d'enum fermée de tous les programmes +pas de Any runtime comme unique représentation de résultat +familles de decoder séparables par capability +ProgramInstructionDecoder / ProgramAccountDecoder = besoins fondamentaux probables, pas obligation de les matérialiser tous sans input réel +ProgramEventDecoder / ProgramReturnDataDecoder = seulement au premier besoin réel +ProgramExecutionPreparer = préparation technique, jamais exécution transactionnelle complète +RAW -> CORE -X-> Program +CORE -> DECODE = première frontière Program future +``` + +### 3.3 Clôture stable `0.2.13` + +Relire : + +```text +CHANGELOG.md +ROADMAP.md + +docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +docs/plans/020-V0_2_13_INTERFACE_PLAN.md +docs/validation/016-V0_2_13_INTERFACE.md + +crates/ksp-interface-lib/README.md +crates/ksp-interface-lib/USAGE.md + +deltas/0.2.13/rel.001.md +``` + +La surface Interface acquise est une contrainte d'entrée de `0.2.14` et ne doit pas être redessinée par commodité. + +### 3.4 Code KSP réel à inventorier avant design + +Inventorier au minimum : + +```text +Cargo.toml +crates/ksp-core-lib/Cargo.toml +crates/ksp-core-lib/src/lib.rs +crates/ksp-core-lib/src/error.rs +crates/ksp-core-lib/src/program_ids.rs + +crates/ksp-interface-lib/Cargo.toml +crates/ksp-interface-lib/src/lib.rs +crates/ksp-interface-lib/src/error.rs +crates/ksp-interface-lib/src/program_account_meta.rs +crates/ksp-interface-lib/src/program_instruction.rs +crates/ksp-interface-lib/tests/public_api.rs +crates/ksp-interface-lib/tests/dependency_boundary.rs +crates/ksp-interface-lib/tests/external_consumer.rs +crates/ksp-interface-lib/tests/release_completeness.rs +``` + +Ne pas supposer qu'un type de l'ancien bot doit être reconstruit s'il n'existe aucune frontière KSP actuelle qui le consomme. + +--- + +## 4. Archive historique `khadhroony-bot3` — audit obligatoire + +L'archive attendue est : + +```text +khadhroony-bot3_v0.5.3-pre.005-fix010.zip +``` + +Elle est une **source historique contrôlée**, jamais une base à extraire par-dessus KSP. + +### 4.1 Fichiers kbot3 prioritaires + +Auditer au minimum lorsqu'ils sont présents : + +```text +ks-lib/src/decoder/api/contracts.rs +ks-lib/src/decoder/api/decoder.rs +ks-lib/src/decoder/api.rs + +ks-lib/src/model/decoded.rs +ks-lib/src/model/replay.rs +ks-lib/src/model/solana.rs + +ks-lib/src/executor/api/execution.rs +ks-lib/src/executor/api/executor.rs +ks-lib/src/executor/api.rs + +ks-lib/src/decoder/solana/core/decoder.rs +ks-lib/src/decoder/spl/token/decoder.rs +ks-lib/src/decoder/spl/token_2022/decoder.rs + +ks-lib/src/lib.rs +ks-lib/Cargo.toml +ks-lib/README.md +ks-lib/USAGE.md + +docs/OPERATION_NAMING_CONVENTION.md +docs/IDL_AUDIT.md +docs/IDL_TO_KB_LIB_NOMENCLATURE.md +docs/architecture/ARCHITECTURE.md +docs/architecture/CRATE_MAP.md +docs/architecture/PIPELINE_ARCHITECTURE.md +``` + +Le but n'est pas de tout lire uniformément : commencer par les contrats API/model, puis utiliser quelques decoders concrets uniquement pour comprendre comment ces contrats étaient réellement consommés. + +### 4.2 Matrice d'héritage obligatoire + +Toute idée significative issue de kbot3 doit être classée : + +```text +REPRENDRE +REDESSINER +REPORTER +REJETER +``` + +Exemples à confronter explicitement : + +```text +DcApiDecoderIdentity +DcApiDecoderSurface +DcApiDecoderCoverageDeclaration +DcApiDecoderRecognition +DcApiDecoderOutcomeStatus +DcApiDecoderDiagnostic +DcApiDecoderProof / ProofKind +DcApiInstructionDecoder +DcApiProtocolDecoder / support No-Maybe-Yes + +ExApiExecutionRequest +ExApiExecutionCapability +ExApiPreparedExecutionPlan +ExApiInstructionExecutor + +MdDecodedProtocolEvent +MdCoreInstructionReplayInput +MdProgramId / MdPubkey / MdInstructionPath +``` + +### 4.3 Héritage pressenti à vérifier, pas à appliquer aveuglément + +Les idées suivantes peuvent être conservées conceptuellement si l'audit les confirme : + +```text +séparer identité, capability, reconnaissance et decode +résultat terminal explicite plutôt qu'une convention implicite +diagnostics structurés plutôt qu'une erreur tierce brute +capabilities déclarées par l'implémentation +support d'implémentations externes +reconnaissance indépendante d'une enum centrale de programmes +séparation decode / préparation d'exécution +``` + +Les éléments suivants doivent au minimum être redessinés avant toute reprise : + +```text +Program IDs / Pubkeys en String -> types Core/Interface typés +serde/JSON par défaut -> seulement si une frontière actuelle l'exige +payload_json générique -> ne pas figer sans modèle réel +executor -> ProgramExecutionPreparer si cette capability entre réellement dans 0.2.14 +policy d'exécution mélangée au plan -> couche ExecutionPolicy future +noms/version en String possédés partout -> contrats bornés et justifiés +``` + +Les éléments suivants sont présumés **reportés** tant qu'une frontière réelle ne les réclame pas : + +```text +signature transaction +slot/block_time comme input générique de decoder +instruction_path / parent CPI / stack_height +logs runtime +return data runtime +transaction_failed / transaction error +balance deltas +hash JSON déterministe du replay input +canonical transaction/replay model +payload persistable D3 complet +materialization +post-execution replay validation +``` + +Ils appartiennent aux futures couches acquisition/CORE/DECODE/Store/Materializer, pas à la foundation Program API isolée. + +Les éléments suivants sont présumés **rejetés** : + +```text +monolithe ks-lib regroupant decoder/executor/materializer/model +répertoire racine géant decoder/ ou executor/ comme architecture officielle future +enum centrale fermée de programmes/protocoles +Any runtime comme seul output ouvert +generic JSON comme substitut à un contrat non conçu +Program ID textuel parallèle au Pubkey Core +dépendance Program API vers Transport/Store/Wallet/Tauri +policy/safety de produit dans Program API +``` + +Toute divergence à ces présomptions doit être justifiée dans le plan `pre.001`. + +--- + +## 5. Sources externes à réauditer en `pre.001` + +`ksp-program-api` est principalement un contrat KSP-owned ; aucune dépendance externe n'est requise par principe. + +Toutefois, si le design proposé dépend d'un comportement Solana, d'une primitive, d'une crate officielle ou d'une contrainte Rust actuelle, vérifier les sources primaires au moment du gate. + +À auditer seulement si pertinent : + +```text +documentation/source officielle Solana/Anza pour les semantics d'instruction réellement invoquées +API courante de solana-pubkey déjà possédée par Core +crate/interface officielle uniquement si elle est réellement nécessaire au contrat public +object safety / dyn compatibility Rust si un registry de trait objects est retenu +``` + +Pour toute nouvelle dépendance candidate : + +```text +version stable réellement courante +source/ownership +features réellement nécessaires +default-features +MSRV/edition si pertinent +graphe transitif +raison pour laquelle Core + Interface ne suffisent pas +``` + +Ne pas ajouter `serde`, `serde_json`, `borsh`, `wincode`, `solana-instruction` ou une crate protocolaire uniquement parce qu'ils existaient dans kbot3. + +--- + +## 6. État validé à préserver depuis `v0.2.13` + +### 6.1 Core + +```text +Error / ErrorCode / ErrorContext / Result possédés par ksp-core-lib +Pubkey canonique possédé/réexporté par Core +registry des Program IDs fondamentaux possédé par Core +``` + +Aucun wrapper `ProgramId(String)` parallèle ne doit être introduit dans Program API. + +### 6.2 Interface + +Surface stable attendue : + +```text +Pubkey +ProgramAccountMeta +ProgramInstruction +MAX_PROGRAM_INSTRUCTION_ACCOUNTS = 255 +MAX_PROGRAM_INSTRUCTION_DATA_LEN = 10_240 +ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED +``` + +Propriétés : + +```text +ProgramInstruction passif +accounts ordonnés et doublons préservés +Program Pubkey opaque accepté +Debug borné +Error Core-owned +aucun serde/codec générique +aucun solana-instruction +aucun logging runtime +``` + +Graphe stable : + +```text +ksp-interface-lib + -> ksp-core-lib + -> solana-pubkey +``` + +`0.2.14` ne doit pas modifier Interface uniquement pour faciliter un premier trait. Si une lacune Wire réelle est découverte, la traiter comme décision explicite et re-sizer la release ; ne pas absorber silencieusement une extension Interface importante dans Program API. + +### 6.3 Autres crates + +Les crates suivantes restent hors chantier : + +```text +ksp-onchain-transport-lib +ksp-offchain-transport-lib +ksp-wallet-lib +ksp-config-lib +ksp-app-*-desk +``` + +Frontières : + +```text +Program API -X-> Transport +Program API -X-> Store +Program API -X-> Wallet +Program API -X-> Materializer +Program API -X-> Tauri +``` + +### 6.4 Pipeline durable + +```text +RAW -> CORE -> DECODE -> SPECIALIZED +``` + +Avec : + +```text +RAW -> CORE -X-> ksp-program-api +CORE -> DECODE peut utiliser ksp-program-api plus tard +``` + +La foundation Program API peut préparer ce futur usage, mais ne crée pas le modèle CORE manquant. + +--- + +## 7. Décisions acquises — ne pas redébattre sans contradiction réelle + +1. la crate cible se nomme `ksp-program-api` ; +2. le suffixe `-api` est volontaire et conforme à `KSP-NAME-002` ; +3. `ksp-program-api` contient les **contrats**, pas les implémentations officielles ; +4. `ksp-program-lib` reste hors de `0.2.14` ; +5. une implémentation externe doit pouvoir dépendre directement de `ksp-program-api` ; +6. un nouveau Program ID externe ne doit pas nécessiter la modification d'une enum centrale KSP ; +7. `ksp-program-api` peut dépendre de Core et d'Interface si leurs types sont réellement utilisés ; +8. `ksp-program-api` ne dépend pas de Transport/Store/Wallet/Materializer ; +9. les Program IDs fondamentaux et `Pubkey` restent Core-owned ; +10. le wire reste Interface-owned ; +11. les codecs wire restent hors Program API ; +12. le decoder vise aussi les surfaces historiques distinguables ; +13. `deprecated` concerne la capability d'exécution, pas la capacité de décodage ; +14. `ProgramExecutor` est abandonné au profit du concept `ProgramExecutionPreparer` pour la préparation pure ; +15. la policy/safety, signature, blockhash, simulation, envoi, confirmation et retry réseau ne sont pas Program API ; +16. les modèles acquisition/replay/CORE complets ne sont pas créés dans `0.2.14` ; +17. kbot3 est une source historique, jamais une autorité architecturale ; +18. une crate `*-api` purement déclarative n'ajoute pas de logging sans comportement réel ; +19. aucun `ksp-api-lib` ou `ksp-interface-api` n'est créé par symétrie ; +20. la release doit rester clôturable dans une seule session et être réduite si le sizing l'exige. + +--- + +## 8. Questions réellement ouvertes à trancher pendant `pre.001` + +### 8.1 Capability initiale minimale + +Décider si la foundation stable contient : + +```text +instruction decoder seulement +instruction decoder + descriptors/capabilities +instruction + account decoder si un input account public réel est démontré +instruction decoder + execution preparation foundation +autre combinaison plus petite justifiée par l'architecture +``` + +Ne pas créer `ProgramAccountDecoder` si aucune forme d'input account stable n'existe encore et que sa définition imposerait d'anticiper CORE. + +### 8.2 Input de decoder instruction + +Le candidat naturel est le contrat Interface existant : + +```text +&ksp_interface_lib::ProgramInstruction +``` + +Auditer s'il suffit à la première capability. + +Ne pas ajouter automatiquement : + +```text +signature +slot +instruction path +CPI ancestry +logs +return data +balance deltas +transaction error +``` + +Ces données ne font pas partie de `ProgramInstruction` et appartiennent à un futur contexte CORE/acquisition. + +### 8.3 Reconnaissance + +Déterminer la forme minimale et déterministe : + +```text +bool +No / Maybe / Yes +compatible + exact +priority +recognized entry code/discriminant +``` + +Éviter un modèle plus riche que les besoins réels du dispatch futur. + +### 8.4 Identité et descriptors + +Décider : + +```text +identité d'implémentation statique ou value object +version d'implémentation nécessaire maintenant ou reportée +Program IDs déclarés via Pubkey typé +capabilities déclarées +surface/coverage machine-readable réellement utile +priorité/conflit entre implémentations nécessaire maintenant ou reporté +``` + +Aucun `String` non borné n'est ajouté par réflexe. + +### 8.5 Outcome de decode + +Auditer les statuts historiques kbot3 : + +```text +Decoded +Ignored +Unsupported +Failed +``` + +Décider lesquels ont un sens dans une API sans payload canonique D3 encore stabilisé. + +Ne pas confondre : + +```text +recognition = ce decoder peut-il identifier cette entrée ? +decode outcome = que s'est-il passé après sélection ? +KSP Error = défaut de contrat/validation de l'appel +``` + +### 8.6 Payload décodé ouvert + +C'est une question critique. + +L'architecture exige à terme un résultat : + +```text +auto-identifiable +extensible +persistable lorsque la frontière Core/Store l'exige +consommable par materializers externes +``` + +Mais `0.2.14` ne doit pas inventer D3 avant Store/Materializer. + +Comparer explicitement : + +```text +enum centrale fermée REJET présumé +Any uniquement REJET présumé +serde_json::Value générique REJET par défaut +trait avec associated output à auditer pour composition hétérogène +payload bytes + media/schema identity à auditer sans anticiper persistence +pas de payload canonique dans la foundation option valide si le contrat decoder peut rester utile autrement +``` + +Si aucune représentation satisfaisante n'est justifiable maintenant, **reporter la sortie canonique complète** plutôt que figer un mauvais contrat public. + +### 8.7 Proof / confidence + +L'ancien bot mélangeait : + +```text +ExactDiscriminator +ExactLayout +Idl +Manual +LogCorrelation +BalanceDelta +Heuristic +Audit +``` + +Distinguer : + +```text +preuves purement instruction-locales +preuves dépendant de logs/balance/CPI/context CORE +metadata d'audit humaine +confidence heuristic +``` + +Les preuves contextuelles ne doivent pas entrer dans `0.2.14` sans input contextuel réel. + +### 8.8 Diagnostics et erreurs + +Décider si un diagnostic Program API dédié apporte déjà une valeur réelle ou si `ksp_core_lib::Error/Result` suffit à la foundation. + +Contraintes : + +```text +aucun payload hostile dans Error/Debug +pas d'erreur tierce brute publique +pas de duplication du Core Error model +codes machine-readable seulement s'ils représentent un état Program réel +``` + +### 8.9 `Send + Sync`, object safety et dyn dispatch + +Si le registry futur doit composer plusieurs implémentations inconnues à compile-time, auditer explicitement : + +```text +Send + Sync +object safety / dyn compatibility +associated types éventuels +lifetime des descriptors statiques +coût/complexité de box/arc +``` + +Ne pas imposer `dyn` si une autre composition publique plus simple suffit ; ne pas définir des traits impossibles à enregistrer si le registry extensible est un besoin de la release. + +### 8.10 Registry + +Distinguer : + +```text +contrat/descripteur d'enregistrement dans Program API +registry runtime concret dans une implémentation/composition future +``` + +`ksp-program-api` ne doit pas devenir une bibliothèque runtime générale uniquement pour stocker des `Vec>` si ce comportement appartient à `ksp-program-lib` ou à un pipeline futur. + +### 8.11 ProgramExecutionPreparer + +L'architecture place ce contrat dans Program API, mais le sizing de `0.2.14` doit décider s'il entre dans la même release foundation. + +Si retenu, il doit rester strictement : + +```text +input technique Program +validation protocolaire +comptes/PDA requis +construction de ProgramInstruction +signers/authorities publics requis +contraintes techniques +``` + +Et exclure : + +```text +wallet concret +secrets +recent blockhash +transaction assembly complète si elle appartient à Execution +simulation RPC +send/confirm +retry réseau +policy mainnet/spend +post-execution storage/replay +``` + +### 8.12 Logging + +Présomption : + +```text +ksp-program-api purement déclaratif -> pas de ksp-logging-lib +pas de constants.rs / TRACING_TARGET +pas de tracing direct +``` + +Si un comportement runtime réel est ajouté malgré le scope, re-sizer la release avant d'introduire logging. + +### 8.13 Sérialisation + +Ne pas ajouter `serde` par anticipation. + +Une API in-memory n'a pas besoin de sérialisation uniquement parce qu'un futur Store pourrait en avoir besoin. + +### 8.14 Sizing + +Évaluer chaque capability candidate selon : + +```text +nécessité immédiate +nombre de types publics +risque de figer une mauvaise API +besoin d'Interface supplémentaire +besoin d'une future couche CORE/Store/Materializer +possibilité de test external-consumer +budget 15-20 min par tranche +clôturabilité dans une session +``` + +Réduire le scope avant l'implémentation lourde si nécessaire. + +--- + +## 9. Objectifs et livrables de `0.2.14` + +### 9.1 Crate et façade + +Créer, après validation `pre.001` : + +```text +crates/ksp-program-api/ +``` + +Avec : + +```text +Cargo.toml +README.md +USAGE.md +src/lib.rs +modules privés +réexports crate-root explicites +unit_tests/ pour unit tests +tests/ pour consumer/public/dependency canaries +``` + +### 9.2 Contrats publics minimaux + +La surface finale doit être issue du plan `pre.001`, pas de cette liste comme checklist forcée. + +Elle doit néanmoins démontrer au minimum : + +```text +un vrai point d'extension Program +un input public stable provenant de Core/Interface +une implémentation externe possible +aucune enum centrale de protocoles +aucune dépendance sur l'implémentation officielle future +``` + +### 9.3 Dependency firewall + +Cible pressentie : + +```text +ksp-program-api + -> ksp-core-lib + -> ksp-interface-lib seulement si surface publique réellement utilisée +``` + +Interdits par défaut : + +```text +ksp-program-lib +ksp-onchain-transport-lib +ksp-offchain-transport-lib +ksp-config-lib +ksp-store-api / ksp-store-lib +ksp-materializer-api / ksp-materializer-lib +ksp-wallet-lib +Tauri +reqwest / tonic / tokio +borsh / wincode / bincode +serde / serde_json sans frontière prouvée +solana-instruction +tracing direct +ksp-logging-lib si API purement déclarative +``` + +Ne pas ajouter `ksp-interface-lib` uniquement pour respecter un graphe dessiné : si aucun type Interface n'est utilisé, `DEP-KSP-005`/minimalité l'emporte. + +### 9.4 External implementation canary + +Le gate de release doit prouver qu'une crate consommatrice séparée peut : + +```text +implémenter le ou les traits publics retenus +utiliser un Program Pubkey non enregistré dans Core +consommer uniquement les exports crate-root +ne dépendre ni de ksp-program-lib ni d'un module privé +``` + +### 9.5 Documentation + +Créer un plan/validation dédiés : + +```text +docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md +docs/validation/017-V0_2_14_PROGRAM_API.md +``` + +Mettre à jour les index correspondants lorsque ces fichiers sont créés. + +README/USAGE de `ksp-program-api` sont réconciliés dans le couloir documentaire final, pas au milieu des tranches fonctionnelles sauf scaffold initial minimal. + +--- + +## 10. Hors périmètre explicite + +Sont hors de `0.2.14`, sauf re-scope documenté après découverte bloquante : + +```text +ksp-program-lib complet +premier decoder Solana Core officiel +premier decoder SPL officiel +vertical slice protocolaire réel +materializers +Store D1/D2/D3/D4 +modèles RAW/CORE complets +instruction path/CPI tree générique +logs/return data/balance deltas normalisés +canonical transaction/replay +ksp-execution-policy-api +ksp-execution-lib +wallet/signature +simulation/send/confirmation +RPC/WS/gRPC +Config +Tauri/apps +IDLs runtime +Anchor decoder générique +registry global de tous les programmes KSP +serde/JSON comme format canonique de decode +``` + +La release ne doit pas devenir une mini-version de toutes les couches futures sous prétexte de « rendre l'API complète ». + +--- + +## 11. Contraintes sécurité, API et architecture spécifiques + +### 11.1 Surface ouverte + +Un nouveau programme externe doit pouvoir être supporté sans modifier une enum `ProgramKind` centrale. + +### 11.2 Types fondamentaux + +Utiliser `ksp_core_lib::Pubkey` / réexports KSP, pas des IDs textuels parallèles. + +### 11.3 Entrées hostiles + +Tout contrat acceptant strings/bytes/vectors doit posséder des bornes déterministes si la taille est attacker-controlled. + +### 11.4 Debug + +Aucun `Debug` public ne doit recopier arbitrairement des payloads instruction ou diagnostics externes volumineux. + +### 11.5 Pas de narrowing implicite + +Les conversions numériques sont explicites et validées. + +### 11.6 Pas de sérialisation accidentelle + +Ne pas dériver `Serialize`/`Deserialize` sur toute l'API uniquement pour faciliter les tests. + +### 11.7 Pas de comportement réseau + +Une méthode de trait Program ne reçoit pas un client RPC, une URL provider ou un wallet. + +### 11.8 Pas de policy cachée + +Un decoder reconnaît/décode ; un preparer prépare. Ils ne décident pas d'une autorisation produit ou mainnet. + +### 11.9 Extensibilité testable + +L'extensibilité doit être prouvée par un consumer externe concret, pas seulement affirmée par documentation. + +### 11.10 API minimale + +Chaque type public doit justifier : + +```text +qui le produit +qui le consomme +pourquoi Core/Interface ne suffit pas +pourquoi il appartient déjà à 0.2.14 +``` + +--- + +## 12. Première mission `0.2.14-pre.001` — gate obligatoire + +### 12.1 Baseline stable + +Vérifier : + +```text +v0.2.13 réel +version Cargo stable +rel.001 présent +Interface stable +absence de Program API/Lib +workspace vert au point de départ ou anomalies documentées +``` + +### 12.2 Audit interne complet + +Produire l'inventaire actuel de : + +```text +Core types utilisables +Interface exports utilisables +frontières dependencies +règles API/Program +architecture Program/Execution +séquence 0.3.x future +``` + +### 12.3 Audit kbot3 + +Avec l'archive `khadhroony-bot3_v0.5.3-pre.005-fix010.zip`, produire une matrice réelle au minimum sur : + +```text +decoder identity/surface/coverage +recognition/support semantics +decode outcomes/diagnostics/proofs +decoder traits +replay/context input +open decoded event model +execution request/capability/prepared plan +ancien executor trait +monolithic ownership +``` + +Classer chaque concept `REPRENDRE / REDESSINER / REPORTER / REJETER`. + +### 12.4 Audit externe ciblé + +Seulement selon les candidats retenus : + +```text +semantics Solana officielles réellement invoquées +Rust dyn/object-safety actuelle si registry dyn retenu +nouvelles dépendances éventuelles +``` + +Aucune recherche externe n'est nécessaire pour justifier une dépendance qui n'est finalement pas ajoutée. + +### 12.5 Matrice d'ownership + +Produire une matrice comparable à : + +```text +concept owner attendu +Pubkey Core +Program IDs fondamentaux Core +ProgramAccountMeta Interface +ProgramInstruction Interface +recognition contract Program API +decoder capability Program API +decoder implementation external / future Program Lib +wire codec Interface +transaction context CORE future CORE +materialized decoded fact future Materializer/D3 +execution policy future ExecutionPolicy +network execution future Execution Lib +``` + +### 12.6 API candidate + +Avant tout code, proposer les signatures publiques candidates : + +```text +traits +descriptors +enums/statuts éventuels +input/output types +error/result +ownership des strings/bytes +Send/Sync/object safety +``` + +Pour chaque élément, indiquer les alternatives rejetées. + +### 12.7 Dependency graph cible + +Proposer puis vérifier un graphe minimal. + +Candidat : + +```text +ksp-program-api +├── ksp-core-lib +└── ksp-interface-lib si utilisé +``` + +Toute autre dépendance doit être justifiée individuellement. + +### 12.8 Threat/API model + +Couvrir au minimum : + +```text +payload hostile +Program Pubkey inconnu +implémentation externe hostile ou incorrecte +panics dans des méthodes default +Debug leak +strings non bornées +registry conflicts si registry retenu +priority ambiguity +false exact recognition +status incohérent avec résultat +dyn/object-safety impossible +closed-world enum accidentelle +``` + +### 12.9 Stratégie de tests + +Prévoir : + +```text +unit tests des value objects retenus +public API crate-root +external consumer/implementation +dependency firewall +release completeness +unknown Program Pubkey +object safety si nécessaire +adversarial bounds/Debug +aucun network smoke +``` + +### 12.10 Sizing et prévision souple recalibrée + +Comparer le scope réel à la prévision initiale de la section 13. + +Chaque tranche intermédiaire vise environ **15-20 minutes de travail effectif maximum** comme budget de planning. + +Si decoder + preparer + registry + open payload ne peuvent pas être stabilisés proprement dans la même session, réduire `0.2.14` avant de coder. + +### 12.11 Documents de sortie `pre.001` + +Créer/mettre à jour au minimum : + +```text +Cargo.toml +docs/plans/000-README.md +docs/plans/021-V0_2_14_PROGRAM_API_PLAN.md +docs/validation/000-README.md +docs/validation/017-V0_2_14_PROGRAM_API.md +deltas/0.2.14/pre.001.md +``` + +Ne pas créer le scaffold lourd de `ksp-program-api` tant que la matrice d'API et le sizing ne sont pas cohérents. + +### Critères de sortie de `pre.001` + +Le gate est réussi seulement si : + +```text +base v0.2.13 vérifiée +archive kbot3 réellement auditée +matrice REPRENDRE/REDESSINER/REPORTER/REJETER documentée +ownership Core/Interface/Program/CORE/Execution explicite +surface API candidate écrite +questions payload/registry/preparer tranchées ou explicitement reportées +dependency graph cible minimal +threat/API model établi +stratégie de tests établie +scope clôturable dans une session +prévision souple recalibrée +aucun développement fonctionnel lourd commencé prématurément +``` + +--- + +## 13. Prévision souple initiale des prereleases + +Cette trajectoire est volontairement **souple**. `pre.001` peut scinder, fusionner ou supprimer des tranches fonctionnelles, mais doit préserver la séparation finale gate technique / réconciliation documentaire / préparation de publication. + +### `pre.001` — Audit KSP + kbot3 + frontières + API model + sizing + +Lectures obligatoires, inventaire stable, audit historique, ownership, threat model, dependency graph, signatures candidates, stratégie de tests et plan détaillé. + +### `pre.002` — Scaffold `ksp-program-api` + façade + dependency firewall + +Créer la crate minimale, l'intégrer au workspace, réexports crate-root, README/USAGE initiaux minimaux, public API canary et exact dependency boundary. Aucun decoder concret. + +### `pre.003` — Identité / capability / reconnaissance minimales + +Introduire uniquement les value objects/statuts réellement retenus en `pre.001`, avec Pubkey typé et invariants bornés. Ne pas encore inventer le payload canonique si celui-ci est reporté. + +### `pre.004` — Premier contrat decoder public + +Matérialiser la capability decoder prioritaire, probablement instruction si le sizing le confirme, contre les types Interface existants. Prouver l'implémentation depuis une crate d'intégration séparée. + +### `pre.005` — Outcome / descriptor / registry contract ou seconde capability réellement retenue + +Cette tranche ne doit exister que pour les éléments explicitement justifiés par `pre.001`. Elle peut servir au descriptor/coverage, à une seconde capability ou au contrat de composition, mais ne remplit pas l'API par symétrie. + +### `pre.006` — Execution preparation foundation uniquement si retenue + +Si `ProgramExecutionPreparer` appartient au scope recalibré, introduire son contrat sans wallet, policy, transport, simulation ou send. Sinon cette tranche est supprimée ou réaffectée à un hardening réel. + +### `pre.007` — External implementation + adversarial/API hardening + +Prouver extensibilité depuis un consumer séparé, Program ID inconnu, object safety/dyn si nécessaire, Debug/bounds/errors, exact export inventory et dependency firewall final. + +### `pre.008` — Gate technique final + +Aucun nouveau développement fonctionnel. Audits Rust, check, Clippy, tests ciblés, workspace complet et graphes Cargo. + +### `pre.009` — Réconciliation documentaire finale + +README/USAGE, plan, validation, séquence/index/références durables réellement touchés. Aucun CHANGELOG/ROADMAP/prompt suivant. + +### `pre.010` — Préparation de publication minimale + +Uniquement : + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +prompt de démarrage de la release suivante +delta pre.010 +``` + +Aucun code/test/README/USAGE/plan/validation/architecture. + +### `rel.001` — Publication stable + +Mécanique de publication uniquement ; aucun rattrapage fonctionnel ou documentaire. + +--- + +## 14. Versionnement, deltas, commits, archives et tags + +Appliquer `docs/rules/VERSION_WORKFLOW.md`. + +Rappels : + +```text +workspace.package.version 0.2.14-pre.N pour une prerelease non-fix +identifiant de livraison X.Y.Z-pre.NNN +delta deltas/0.2.14/pre.NNN.md +fix local à sa responsabilité : pre.NNN-fix.MMM +version Cargo d'un fix code/runtime : 0.2.14-pre.N.fix.M +``` + +À partir de `0.1.x`, chaque delta est commité. + +Commit attendu : + +```text +v0.2.14-pre.NNN +``` + +Les prereleases/fixes ne nécessitent pas de tag Git. + +La release stable reçoit : + +```text +commit v0.2.14-rel.001 +tag v0.2.14 +workspace.package.version = 0.2.14 +``` + +Archives overlay : + +```text +ksp-general-0.2.14-pre.NNN.zip +``` + +Elles contiennent uniquement les fichiers ajoutés/modifiés + delta correspondant. + +Ne jamais remplacer silencieusement une archive publiée sous le même identifiant. + +--- + +## 15. Validation opérateur et procédure d'application + +Après application d'un 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.2.14 +cargo check --workspace +cargo clippy --workspace --all-targets +``` + +Puis les tests ciblés de `ksp-program-api` dès que la crate existe : + +```bash +cargo test -p ksp-program-api +``` + +Aux gates techniques/final : + +```bash +cargo test --workspace +cargo tree -p ksp-program-api --edges normal +cargo tree --duplicates +``` + +Si une nouvelle dépendance externe est introduite : + +```bash +cargo tree -i +``` + +selon le besoin. + +Aucun smoke réseau/live n'est attendu pour une API purement déclarative. + +Ne pas déclarer un gate vert si une commande demandée n'a pas été réellement exécutée. + +--- + +## 16. Tests et canaris attendus + +### 16.1 Public API + +Le consumer doit utiliser exclusivement les exports crate-root. + +### 16.2 External implementation + +Une crate de test séparée doit implémenter la capability publique retenue pour un Program Pubkey opaque/non enregistré. + +### 16.3 Dependency firewall + +Le manifest Program API doit rester limité aux dépendances nécessaires et ne tirer aucun runtime réseau/storage/UI. + +### 16.4 Open-world + +Aucune enum centrale de Program IDs/protocoles ne doit être nécessaire pour enregistrer ou utiliser l'implémentation externe canari. + +### 16.5 Recognition/decode invariants + +Selon le contrat retenu : + +```text +unknown input +recognized but unsupported +exact/partial recognition +status incohérent +malformed payload +empty payload +max boundary +one-above boundary +``` + +### 16.6 Debug/error safety + +Aucun payload hostile ou valeur externe arbitraire n'est copié dans Error/Debug sans borne. + +### 16.7 Object safety + +Si le design exige `dyn Trait`, ajouter un canari de compilation/usage réel. Sinon ne pas imposer ce gate artificiellement. + +### 16.8 Release completeness + +Verrouiller la surface réellement décidée sans rendre impossible son extension future. + +--- + +## 17. Critères de clôture de `0.2.14` + +La release peut être publiée seulement si : + +```text +ksp-program-api existe et respecte les règles *-api +surface publique minimale documentée +au moins une capability Program réellement implémentable depuis une crate externe +aucune enum centrale fermée de programmes +aucun ksp-program-lib anticipé +aucune dépendance Transport/Store/Wallet/Materializer/Tauri +aucun codec wire direct Program API +aucun logging runtime inutile +aucun replay/CORE context artificiellement inventé +external implementation canary PASS +public API canary PASS +dependency firewall PASS +adversarial/API hardening PASS +cargo test -p ksp-program-api PASS +cargo test --workspace PASS +graphe Cargo inspecté +documentation durable réconciliée +CHANGELOG/ROADMAP/prompt suivant préparés dans la dernière prerelease dédiée +``` + +Si `ProgramExecutionPreparer` a été reporté par `pre.001`, son absence n'est pas un échec de release : le plan doit simplement indiquer explicitement son prochain owner/release. + +--- + +## 18. Release/session suivante envisagée + +Après `0.2.14`, la séquence active prévoit : + +```text +0.3.1 — ksp-store-api + ksp-store-lib, RAW only +``` + +Puis : + +```text +0.3.2 — extension ksp-interface-lib pour wires génériques acquisition/CORE +0.3.3 — ksp-job-api + backfill +0.3.4 — application backfill/RAW +``` + +`0.2.14` ne doit pas aspirer ces contrats pour rendre Program API artificiellement « complet ». + +Le prompt suivant préparé en fin de release sera donc consacré à `0.3.1`, sauf décision de roadmap explicitement modifiée avant la clôture. + +--- + +## 19. Instruction d'ouverture + +À l'ouverture de la session `0.2.14` : + +1. vérifier que la base est exactement `v0.2.13` ; +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 listées dans les sections 3.1 et 3.2 ; +4. inventorier la surface réelle Core + Interface de `v0.2.13` ; +5. auditer les contrats kbot3 listés en section 4 ; +6. produire la matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` ; +7. proposer ownership, API candidate, dependency graph, threat/API model et stratégie de tests ; +8. recalibrer la prévision souple et le sizing ; +9. créer seulement ensuite le delta/documentation `0.2.14-pre.001` ; +10. **ne pas commencer le scaffold fonctionnel `ksp-program-api` avant que le gate `pre.001` soit cohérent**. + +Le premier message de travail doit commencer par l'audit de la base réelle et des deux sources KSP/kbot3, pas par une proposition de code fondée sur la mémoire.