# Prompt de démarrage `0.2.13` — Interface foundation ## 1. Identité de la release et base exacte La base attendue est **exclusivement** la release stable : ```text v0.2.12 ``` Ne pas ouvrir `0.2.13` depuis `0.2.12-pre.*`, `0.2.12-pre.*-fix.*`, une archive intermédiaire, l'ancien projet kbot3 ou un souvenir de session. Si une archive opérateur de `v0.2.12` est fournie au démarrage, cette archive réelle est la première autorité devant les snippets, anciennes archives, anciens prompts et mémoire de conversation. La release à ouvrir est : ```text 0.2.13 — Interface foundation ``` La première tranche est : ```text 0.2.13-pre.001 ``` `pre.001` est obligatoirement une tranche d'**audit actuel + audit d'héritage kbot3 + brainstorming + décision de frontières + sizing**. Aucune implémentation fonctionnelle lourde de `ksp-interface-lib` ne doit précéder ce gate. ## 2. Mission Introduire la première surface de `ksp-interface-lib` comme **façade wire KSP publique, passive, bornée et réutilisable**, destinée aux implémentations officielles futures et aux implémentations externes. La release doit préparer proprement `0.2.14 — ksp-program-api` sans l'implémenter par anticipation. La séparation cible est : ```text ksp-core-lib primitives KSP fondamentales / Error / Pubkey / Program IDs ksp-interface-lib données et contrats wire publics passifs sérialisation / validation / bornes / compatibilité aucun comportement Program concret ksp-program-api # 0.2.14 traits et contrats comportementaux extensibles reconnaissance / decode / build / capabilities selon audit ksp-program-lib # plus tard implémentations officielles concrètes ``` `ksp-interface-lib` ne doit devenir ni un SDK Solana monolithique, ni un `ks-lib` renommé, ni une crate fourre-tout pour decoder/materializer/executor/store/pipeline. ## 3. Autorités et lectures obligatoires avant toute décision Relire depuis la base réelle `v0.2.12`, au minimum : ```text README.md RULES.md ROADMAP.md CHANGELOG.md Cargo.toml docs/000-README.md docs/rules/RULES_KSP.md docs/rules/RULES_RUST.md docs/rules/PROMPT_STRUCTURE.md docs/rules/VERSION_WORKFLOW.md docs/rules/FILE_CONTRACTS.md docs/architecture/001-LAYERS.md docs/architecture/002-DEPENDENCIES.md docs/architecture/003-COMPONENT_CONTRACTS.md docs/architecture/004-COMPONENT_INVENTORY.md docs/architecture/005-DEPENDENCY_GRAPH.md docs/architecture/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md ``` Relire aussi les surfaces publiques réelles de : ```text crates/ksp-core-lib crates/ksp-onchain-transport-lib crates/ksp-offchain-transport-lib ``` Le but est d'éviter de dupliquer une primitive déjà possédée par Core ou de faire remonter dans Interface un DTO privé appartenant encore à Transport. ## 4. Héritage `khadhroony-bot3` : source d'idées, jamais autorité Une archive historique fournie avant la publication de `v0.2.12` est : ```text khadhroony-bot3_v0.5.3-pre.005-fix010.zip ``` Elle doit être traitée comme une **source d'idées à réévaluer**, pas comme une base de code ni comme une architecture à restaurer. La reconnaissance préalable à ce prompt a identifié dans l'ancien `ks-lib` plusieurs familles conceptuelles utiles : ```text modèles wire / identité signature slot program id / pubkey instruction path source kind contract version contexte d'instruction instruction top-level / CPI parent path stack height accounts résolus instruction accounts payload brut return data logs état d'échec transaction contrats d'extension historiques decoder identity / surfaces / coverage recognition / outcome diagnostics / proof external decoder compile canary prepared execution plans / required signers / policy event materializer contract ``` L'ancien projet contient également deux leçons négatives importantes : 1. `ks-lib` concentre plusieurs centaines de fichiers de modèles, decoders, materializers et executors ; **ne pas reproduire ce monolithe** ; 2. plusieurs générations d'API decoder coexistent (`DcApiProtocolDecoder` puis contrat contextuel plus riche) ; **ne pas créer deux API concurrentes par compatibilité avec l'ancien projet**. En `pre.001`, produire une matrice explicite pour chaque idée pertinente : ```text REPRENDRE comme concept REDESSINER selon KSP actuel REPORTER vers ksp-program-api / ksp-program-lib / 0.3.2+ REJETER ``` Si l'archive historique n'est pas disponible dans la nouvelle session, les éléments ci-dessus constituent seulement un seed de reconnaissance ; ne pas inventer le contenu manquant. L'opérateur peut fournir de nouveau l'archive si une inspection plus profonde est nécessaire. ## 5. Frontière stricte `Interface` / `Program API` / `Program Lib` ### `ksp-interface-lib` — autorisé dans `0.2.13` La crate peut posséder, après audit `pre.001`, des types publics KSP représentant des **faits wire génériques** nécessaires à la future extension Program : identités, chemins d'instruction, comptes/meta, données binaires bornées, contextes minimaux, enveloppes/version de contrat, sérialisation déterministe et validation locale. Les noms et le périmètre exacts doivent être décidés à partir des besoins démontrés de `0.2.14`, pas copiés depuis kbot3. ### `ksp-program-api` — réservé à `0.2.14` Ne pas introduire dans `0.2.13` de trait comportemental public qui présuppose déjà l'architecture Program finale, notamment un équivalent prématuré de : ```text InstructionDecoder ProtocolDecoder ProgramDecoder Executor TypedInstructionExecutor Materializer ProgramRegistry comportemental ``` Les notions historiques `identity`, `surfaces`, `coverage`, `recognize`, `decode`, `prepared plan`, `required signers`, `materialize` sont des **inputs de conception pour `0.2.14+`**, sauf si `pre.001` démontre qu'un type de données passif doit vivre dans Interface indépendamment du trait qui le consommera. ### `ksp-program-lib` — hors scope Aucun decoder/executor/materializer officiel concret de System, SPL Token, Token-2022, Metadata, Anchor, Meteora, Raydium, Pump, Orca, Jupiter ou autre programme n'est implémenté ici. ## 6. Frontière avec RAW / CORE / Store Le pipeline durable reste : ```text RAW -> CORE -> DECODE -> SPECIALIZED ``` `0.2.13` ne doit pas anticiper `0.3.1`/`0.3.2` en transformant `ksp-interface-lib` en modèle complet d'acquisition ou de persistence RAW/CORE. Le roadmap réserve explicitement à `0.3.2` l'extension d'Interface avec les wires génériques nécessaires aux acquisitions et à la future normalisation CORE. Donc : - n'ajouter maintenant que les contrats indispensables à la future frontière Program ; - ne pas créer tables, DTO Store, replay ledger, observation persistence ou jobs ; - ne pas figer prématurément un `CoreInstructionReplayInput` complet simplement parce que kbot3 en possédait un ; - si un contexte transactionnel riche est utile mais pas encore requis par `0.2.14`, le documenter comme candidat `0.3.2+`. ## 7. Dépendances et ownership `ksp-interface-lib` doit rester bas niveau et réutilisable. Baseline souhaitée à confronter au gate `pre.001` : ```text ksp-interface-lib -> ksp-core-lib ``` Ajouter seulement les crates de sérialisation/utilitaires réellement nécessaires et autorisées par les règles workspace. Interdictions initiales : ```text Interface -X-> Config Interface -X-> Logging runtime Interface -X-> Transport Interface -X-> Wallet Interface -X-> Store Interface -X-> Tauri Interface -X-> reqwest / tonic / tokio runtime Interface -X-> SDK/clients provider ``` Ne pas réintroduire un agrégat Solana ou des crates protocole simplement pour importer des types pratiques. Les représentations publiques doivent rester KSP-owned lorsque cela protège la stabilité et le firewall du workspace. Toute exception doit être justifiée par l'audit des règles et des dépendances officielles actuelles. ## 8. Qualités obligatoires de la première surface wire Toute surface retenue doit viser : - types publics documentés et consommables depuis une crate externe ; - ownership explicite des identités et données ; - sérialisation/désérialisation uniquement lorsqu'elle est utile au contrat ; - aucune conversion canonique lossless -> `f64` ; - longueurs et collections bornées avant allocations pathologiques ; - données binaires sans `Debug` accidentellement gigantesque ou secret ; - distinction entre absence, valeur vide et valeur présente lorsque le wire la possède réellement ; - ordre préservé lorsque l'ordre Solana est sémantique ; - aucune dépendance à un backend de stockage ou à un transport ; - `#[non_exhaustive]` sur les enums publics susceptibles d'évoluer lorsqu'approprié ; - tests downstream-style prouvant que le contrat public suffit à un consumer externe. Ne pas versionner un contrat wire par réflexe. Si une version explicite est retenue, `pre.001` doit expliquer **ce qui nécessite une évolution de contrat** et comment la compatibilité sera gérée. ## 9. Questions obligatoires de `pre.001` Avant d'écrire la surface définitive, répondre explicitement à ces questions : 1. Quel besoin précis de `0.2.14` exige déjà `ksp-interface-lib` ? 2. Quels types actuellement dans Core/Transport peuvent être réutilisés sans duplication ? 3. Quelles données doivent être KSP-owned plutôt que des types Solana externes ? 4. La première surface doit-elle couvrir instruction uniquement, instruction + account, ou un autre minimum ? 5. Quelles informations CPI sont indispensables dès maintenant : path, parent, stack height, aucune ? 6. Les logs, return data, balance deltas et erreurs transactionnelles appartiennent-ils à `0.2.13`, à `0.3.2`, ou à une autre couche ? 7. Quel encodage public représente les bytes sans ambiguïté et avec bornes raisonnables ? 8. Quels invariants peuvent être validés localement sans prétendre valider la sémantique d'un Program ? 9. Quels anciens concepts kbot3 sont réellement utiles et lesquels reflètent seulement son ancienne architecture ? 10. Le scope tient-il raisonnablement dans une session de release ? Sinon, réduire `0.2.13` avant toute implémentation lourde. ## 10. Livrables attendus de `pre.001` `pre.001` doit produire au minimum : - audit de la surface actuelle de Core/Transport pertinente ; - audit ciblé de l'héritage kbot3 si l'archive est disponible ; - matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` ; - décision exacte des types/wires qui appartiennent à `0.2.13` ; - décision explicite de ce qui reste pour `0.2.14` et `0.3.2+` ; - graphe de dépendances cible ; - threat/robustness model wire : tailles, allocations, debug, malformed input ; - plan détaillé et validation dédiés ; - sizing final et forecast de prereleases recalibré. `pre.001` peut rester principalement documentaire. Il ne doit pas créer une grosse API uniquement pour respecter le forecast initial ci-dessous. ## 11. Prévisions souples initiales Ces tranches sont un **forecast de départ**, pas un contrat rigide. `pre.001` doit les fusionner, scinder ou supprimer si l'audit le justifie. ### `pre.001` — Audit actuel + héritage kbot3 + frontières + sizing **Statut : prévu** Audit des besoins réels de `0.2.14`, des surfaces existantes Core/Transport, de l'archive kbot3 et des dépendances. Décider le minimum wire exact, créer plan/validation et confirmer le sizing. ### `pre.002` — Scaffold `ksp-interface-lib` + firewall **Statut : prévu** Créer la crate, sa façade publique minimale, README/USAGE initiaux, tests de dépendances et canari de consommation externe, sans comportement Program. ### `pre.003` — Primitives wire communes retenues **Statut : prévu** Introduire uniquement les identités, wrappers, bornes et représentations communes confirmées par `pre.001`, en réutilisant Core lorsque possible. ### `pre.004` — Wire instruction **Statut : prévu** Matérialiser le contrat d'instruction générique retenu : program identity, comptes/meta ordonnés, données et contexte minimal démontré. Pas de decode. ### `pre.005` — Wire account/contexte complémentaire retenu **Statut : prévu** Ajouter seulement le second lot démontré par l'audit — account wire et/ou contexte strictement nécessaire au futur Program API. Ne pas forcer cette tranche si le scope minimal n'en a pas besoin. ### `pre.006` — Sérialisation, bornes et adversarial **Statut : prévu** Round-trips déterministes, malformed inputs, tailles/collections hostiles, représentation binaire, `Debug` sûr, ordre et états optionnels. ### `pre.007` — External consumer contract + API hardening **Statut : prévu** Canaris downstream-style prouvant qu'une crate externe peut construire/lire la surface publique sans imports privés ni dépendances Program. Réaudit de la surface exposée et du graph Cargo. ### `pre.008` — Gate technique et réconciliation documentaire finale **Statut : prévu** Workspace complet, Clippy/tests, audit public API/dependencies, README/USAGE/architecture/plan/validation. Aucune extension fonctionnelle opportuniste. ### `pre.009` — Préparation de publication **Statut : prévu** Couloir minimal : prompt `0.2.14`, `CHANGELOG.md`, `ROADMAP.md`, version et delta. Ne pas fusionner avec la réconciliation documentaire si les règles de lifecycle en vigueur l'interdisent. ### `rel.001` — Publication stable **Statut : prévu** Passage à `0.2.13`, gate final requis par les règles, commit/tag stable `v0.2.13` et conservation du seul tag stable attendu par le workflow KSP. ## 12. Tests et canaris attendus Le plan final doit au moins prévoir : ```text cargo fmt --all python3 scripts/audit_rust_workspace_rules.py python3 scripts/audit_markdown_tables.py ... cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-interface-lib cargo test --workspace ``` Canaris spécifiques attendus selon le scope retenu : - external consumer compile test depuis l'API publique ; - dependency firewall ; - aucun comportement Program concret ; - aucune dépendance Config/Transport/Store/Tauri ; - malformed/oversized input avant allocation pathologique ; - sérialisation/round-trip exacte si serde fait partie du contrat ; - ordre des comptes/instructions préservé ; - distinction des options wire utiles ; - surface publique documentée et exports complets. Aucun smoke réseau n'est requis par défaut pour une crate wire pure. Ne pas inventer un test live sans valeur technique réelle. ## 13. Hors scope explicite Pour `0.2.13`, ne pas implémenter : - `ksp-program-api` ; - `ksp-program-lib` ; - decoder Program concret ; - Anchor generic decoder ; - IDL parser/generator ; - materializer ; - executor / transaction builder Program ; - Store/RAW/CORE persistence ; - jobs/workers/pipelines ; - UI/Tauri ; - provider réseau ; - plugin dynamique / ABI stable C / WASM sandbox ; - auto-discovery de Program IDs ; - registry de plugins runtime ; - compatibilité automatique avec les types historiques `ks-lib`. Les IDL et implémentations de l'ancien projet peuvent servir de références futures mais ne constituent pas la mission de cette release. ## 14. Discipline de delta et de session Pour chaque prerelease : - partir exclusivement de la tranche opérateur réellement validée ; - relire les règles/architecture pertinentes avant de rédiger ou modifier un contrat ; - produire un delta immuable `deltas/0.2.13/pre.NNN.md` ; - en cas de défaut, produire `pre.NNN-fix.MMM` strictement limité à la responsabilité de la tranche ; - ne pas modifier `ROADMAP.md` en détail pendant les prereleases ordinaires ; - réserver `CHANGELOG.md` à la clôture ; - préserver le format RustRover de tous les tableaux Markdown touchés ; - exécuter les gates applicables avant de fermer une tranche ; - garder la release dimensionnée pour une seule session de chat. Les prévisions ci-dessus ne justifient jamais d'ajouter une surface qui n'est pas démontrée par l'audit.