# 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.