From c73e4c0aeccc307c26c85bfa7de6a90a9491ea38 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Thu, 27 Aug 2026 20:31:50 +0200 Subject: [PATCH] v0.2.12-pre.011-fix.001 --- deltas/0.2.12/pre.011-fix.001.md | 138 +++ prompts/018-V0_2_13_START_PROMPT.md | 1414 ++++++++++++++++++++++----- 2 files changed, 1323 insertions(+), 229 deletions(-) create mode 100644 deltas/0.2.12/pre.011-fix.001.md diff --git a/deltas/0.2.12/pre.011-fix.001.md b/deltas/0.2.12/pre.011-fix.001.md new file mode 100644 index 0000000..545478c --- /dev/null +++ b/deltas/0.2.12/pre.011-fix.001.md @@ -0,0 +1,138 @@ + + + +# Delta `0.2.12-pre.011-fix.001` — mise en conformité du prompt `0.2.13` + +## Base requise + +```text +0.2.12-pre.011 +workspace.package.version = 0.2.12-pre.11 +``` + +Le gate de `pre.010` était intégralement propre. `pre.011` a ensuite produit le prompt `0.2.13`, `CHANGELOG.md` et `ROADMAP.md` dans le couloir minimal de préparation de publication. + +## Objectif + +Corriger uniquement la responsabilité prompt de `pre.011` après comparaison explicite avec : + +```text +docs/rules/PROMPT_STRUCTURE.md +prompts/016-V0_2_11_START_PROMPT.md +prompts/017-V0_2_12_START_PROMPT.md +``` + +Le prompt initial allait dans la bonne direction fonctionnelle mais n'était pas assez autonome ni assez complet par rapport au contrat normatif KSP. + +## Défauts corrigés + +Le prompt `version: 1` : + +- ne matérialisait pas toutes les sections obligatoires de `PROMPT_STRUCTURE.md` ; +- ne séparait pas assez clairement état validé, décisions acquises, questions ouvertes, objectifs, contraintes, validations et critères de clôture ; +- ne possédait pas de section `Instruction d'ouverture` immédiatement repérable ; +- fusionnait `gate technique` et `réconciliation documentaire` dans le forecast alors que les couloirs de fermeture doivent être distincts ; +- référençait deux anciens noms de fichiers architecture inexistants : `001-LAYERS.md` et `002-DEPENDENCIES.md` ; +- omettait la référence centrale `docs/architecture/006-WIRE_AND_PROGRAM.md` dans l'ordre de lecture ; +- ne donnait pas une procédure opérateur, un gate Rust complet ni des critères de clôture assez détaillés ; +- rendait trop implicite la frontière entre wire Program-facing de `0.2.13` et wires génériques acquisition/CORE réservés notamment à `0.3.2`. + +## Correction + +`prompts/018-V0_2_13_START_PROMPT.md` passe à `version: 2` et suit désormais la structure autonome utilisée par les prompts KSP récents : + +```text +identité/base exacte +mission/résultat attendu +sources internes ordonnées +sources externes à réauditer +état stable à préserver +décisions acquises +questions ouvertes +audit kbot3 contrôlé +objectifs/livrables +hors scope +contraintes sécurité/API/architecture +première mission pre.001 + critères de sortie +prévision souple détaillée +versionnement/deltas/commits/tags +validation opérateur +tests/canaris +critères de clôture +release suivante +instruction d'ouverture +``` + +Le forecast de fermeture est corrigé en : + +```text +pre.008 gate technique final +pre.009 réconciliation documentaire finale +pre.010 préparation de publication minimale +rel.001 publication stable +``` + +La reconnaissance kbot3 reste un input non normatif. `pre.001` doit toujours classer chaque idée `REPRENDRE / REDESSINER / REPORTER / REJETER` et ne doit pas recréer l'ancien monolithe `ks-lib`. + +## Version Cargo + +Correctif exclusivement documentaire/prompt : + +```text +workspace.package.version reste 0.2.12-pre.11 +``` + +Conforme à `VER-ID-008`. + +## Fichiers ajoutés + +```text +deltas/0.2.12/pre.011-fix.001.md +``` + +## Fichiers modifiés + +```text +prompts/018-V0_2_13_START_PROMPT.md +``` + +## Fichiers supprimés + +Aucun. + +## Fichiers explicitement non rouverts + +```text +Cargo.toml +CHANGELOG.md +ROADMAP.md +README / USAGE +plans / validations +architecture +règles normatives +code / tests / config +``` + +## Validations exécutées + +```text +comparaison section par section avec PROMPT_STRUCTURE.md +comparaison de structure avec prompts 016 et 017 +vérification des chemins architecture réels +vérification de la séparation des trois couloirs de fermeture +vérification du scope strict prompt-only +``` + +Les audits Markdown KSP sont exécutés sur l'arbre reconstruit avant livraison du ZIP. + +## Validations non exécutées + +Aucune validation Cargo n'est requise par ce fix documentaire, et aucune commande Cargo n'est revendiquée comme exécutée pour ce delta. + +## Étape suivante + +Après application et audit Markdown opérateur, `pre.011-fix.001` remplace uniquement le prompt de reprise de `0.2.13`. La prochaine étape reste : + +```text +0.2.12-rel.001 +``` diff --git a/prompts/018-V0_2_13_START_PROMPT.md b/prompts/018-V0_2_13_START_PROMPT.md index ec33ae3..3fc828e 100644 --- a/prompts/018-V0_2_13_START_PROMPT.md +++ b/prompts/018-V0_2_13_START_PROMPT.md @@ -1,9 +1,9 @@ - + -# Prompt de démarrage `0.2.13` — Interface foundation +# Prompt de démarrage `0.2.13` — Interface / wire foundation -## 1. Identité de la release et base exacte +## 1. Identité de la release et base exacte requise La base attendue est **exclusivement** la release stable : @@ -11,12 +11,23 @@ La base attendue est **exclusivement** la release stable : 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. +Ne pas ouvrir `0.2.13` depuis : + +```text +0.2.12-pre.* +0.2.12-pre.*-fix.* +0.2.12-rel.* non encore validé stable +une archive intermédiaire de travail +l'ancien dépôt khadhroony-bot3 +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. Une divergence entre la base réelle et ce prompt déclenche un audit explicite ; elle ne se résout jamais par supposition. La release à ouvrir est : ```text -0.2.13 — Interface foundation +0.2.13 — Interface / wire foundation ``` La première tranche est : @@ -25,379 +36,1324 @@ La première tranche est : 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. +`pre.001` est obligatoirement une tranche **lecture + audit interne + audit d'héritage kbot3 + audit externe ciblé + brainstorming + frontières + dependency graph + threat/robustness model + sizing + planification**. -## 2. Mission +Aucune API wire lourde, aucun trait Program et aucun portage de code kbot3 ne doit commencer avant la sortie cohérente de ce gate. -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 : +À l'ouverture, vérifier au minimum : ```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 +git describe / tag stable si metadata Git disponible +workspace.package.version = 0.2.12 +deltas/0.2.12/rel.001.md présent +prompts/018-V0_2_13_START_PROMPT.md présent +ksp-interface-lib absent au démarrage sauf contradiction de la base réelle +ksp-program-api absent au démarrage sauf contradiction de la base réelle ``` -`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 +## 2. Mission et résultat attendu -Relire depuis la base réelle `v0.2.12`, au minimum : +La mission de `0.2.13` est d'introduire la **première surface de `ksp-interface-lib`**, conformément à l'architecture KSP actuelle : ```text -README.md -RULES.md -ROADMAP.md -CHANGELOG.md -Cargo.toml +façade wire officielle KSP +API publique wire réutilisable +contrats passifs / codecs / validation locale +pas de comportement Program +pas de runtime réseau +pas de persistence +``` +La release doit préparer proprement : + +```text +0.2.14 — ksp-program-api foundation +``` + +sans implémenter cette release par anticipation. + +Résultat attendu à la clôture, sous réserve du scope exact décidé en `pre.001` : + +```text +ksp-interface-lib existe comme crate membre du workspace +façade publique explicite via crate root +surface wire minimale réellement justifiée par le futur Program API +ownership Core / Interface / Program clairement séparé +codec(s) wire seulement si un contrat réel l'exige +validation/bornes déterministes des données exposées +aucune logique decode/reconnaissance/exécution/materialisation +aucune dépendance reverse vers Transport/Store/Wallet/App +aucune dépendance protocolaire opportuniste non auditée +canari consumer externe/public API +canaris de dependency firewall +round-trips/adversarial tests si sérialisation retenue +README/USAGE durables réconciliés avant publication +plan/validation de release complets +prompt 0.2.14 préparé dans le couloir final dédié +``` + +Le résultat n'est **pas** de recréer un modèle universel de transaction/replay ni de remplir Interface par symétrie avec l'ancien `ks-lib`. + +La question centrale de la release est : + +> quel est le **minimum wire public KSP-owned** qu'il faut stabiliser maintenant pour que `ksp-program-api` puisse être conçu proprement en `0.2.14`, sans anticiper les wires génériques RAW/CORE réservés aux séries suivantes ? + +--- + +## 3. Sources de vérité internes obligatoires — ordre de lecture + +### 3.1 Règles globales + +Lire d'abord, dans cet ordre : + +```text +RULES.md docs/000-README.md + +docs/rules/RULES_GENERAL.md docs/rules/RULES_KSP.md docs/rules/RULES_RUST.md -docs/rules/PROMPT_STRUCTURE.md -docs/rules/VERSION_WORKFLOW.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 +``` -docs/architecture/001-LAYERS.md -docs/architecture/002-DEPENDENCIES.md +Le présent prompt est un contrat opératoire autonome, mais **ne remplace aucune règle normative**. + +Rappels qui conditionnent directement cette release : + +```text +Rust 2024 +unsafe / unwrap / expect / panic interdits selon les règles KSP +? interdit en production selon les lints KSP +#![warn(missing_docs)] +#![deny(unreachable_pub)] +#![forbid(unsafe_code)] + +pas de pub mod comme raccourci de façade +surface publique réexportée explicitement depuis crate root +unit tests sous unit_tests/ autant que possible +tests/ réservé aux tests d'intégration consommant l'API publique +Error/Result communs possédés par ksp-core-lib +Program IDs fondamentaux possédés par ksp-core-lib +Pubkey consommé via ksp-core-lib lorsque la frontière KSP l'exige +``` + +Règles wire/dependency à relire particulièrement : + +```text +KSP-WIRE-001..003 +DEP-WIRE-001..007 +DEP-PROGRAM-001..004 +DEP-KSP-001..005 +DEP-CARGO-001..007 +``` + +Après toute modification Rust : + +```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.13 +``` + +Une commande non exécutée n'est jamais déclarée PASS. + +### 3.2 Architecture durable à préserver + +Lire ensuite, dans cet ordre : + +```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/010-APPS_SERVICES_SCENARIOS_AND_CONTROL.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/006-WIRE_AND_PROGRAM.md` est la référence architecturale centrale de cette release. + +Points acquis à préserver : + +```text +ksp-interface-lib = façade wire officielle + API wire publique +pas de ksp-interface-api séparée actuellement +Program IDs fondamentaux restent dans Core +Interface peut posséder codecs/layouts/discriminants/seeds/constructeurs wire lorsqu'ils appartiennent réellement au contrat +Interface ne possède pas interprétation métier/decode Program/policy/exécution réseau +ksp-program-api est ouvert/extensible et vient ensuite +ksp-program-lib porte plus tard les implémentations officielles +une extension externe peut consommer les wires officiels sans dépendre de ksp-program-lib +RAW -> CORE reste générique et ne dépend pas de Program +CORE -> DECODE est la première frontière qui peut utiliser Program API +``` + +Ne pas remplacer ces décisions par la structure de kbot3. + +### 3.3 Plans, roadmap et clôture `0.2.12` + +Relire : + +```text +ROADMAP.md +CHANGELOG.md docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +docs/plans/019-V0_2_12_SOL_PRICES_DESK_PLAN.md +docs/validation/015-V0_2_12_SOL_PRICES_DESK.md + +deltas/0.2.12/rel.001.md ``` -Relire aussi les surfaces publiques réelles de : +Le but n'est pas de rouvrir `0.2.12`, mais de confirmer la base stable et la séquence retenue : ```text -crates/ksp-core-lib -crates/ksp-onchain-transport-lib -crates/ksp-offchain-transport-lib +0.2.13 interface/wire foundation +0.2.14 program-api foundation +0.3.1 Store RAW +0.3.2 extension Interface pour wires génériques acquisition/CORE ``` -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. +Cette séquence est une contrainte importante : `0.2.13` ne doit pas absorber prématurément `0.3.2`. -## 4. Héritage `khadhroony-bot3` : source d'idées, jamais autorité +### 3.4 Code réel à inventorier avant design -Une archive historique fournie avant la publication de `v0.2.12` est : +Inventorier au minimum : ```text -khadhroony-bot3_v0.5.3-pre.005-fix010.zip +Cargo.toml +crates/ksp-core-lib/Cargo.toml +crates/ksp-core-lib/src/lib.rs +crates/ksp-core-lib/src/program_ids.rs + +crates/ksp-onchain-transport-lib/Cargo.toml +crates/ksp-onchain-transport-lib/src/lib.rs +crates/ksp-onchain-transport-lib/src/rpc_common.rs +crates/ksp-onchain-transport-lib/src/rpc_accounts.rs +crates/ksp-onchain-transport-lib/src/rpc_transactions.rs +crates/ksp-onchain-transport-lib/src/rpc_blocks.rs +crates/ksp-onchain-transport-lib/src/ws_*.rs selon types réellement pertinents +crates/ksp-onchain-transport-lib/src/grpc_*.rs selon types réellement pertinents ``` -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 : +L'inventaire doit distinguer : ```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 +type fondamental déjà possédé par Core +wire/provider DTO privé de Transport +type générique potentiellement partageable mais actuellement transport-owned +contrat nouveau réellement nécessaire à Interface +type qui appartient seulement à RAW/CORE plus tard ``` -L'ancien projet contient également deux leçons négatives importantes : +Ne pas déplacer un DTO Transport vers Interface uniquement pour réduire une duplication apparente. Ownership et stabilité priment. -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 : +## 4. Sources externes normatives à réauditer en `pre.001` + +La release ne doit pas figer un wire Solana ou choisir un codec depuis des souvenirs historiques. + +Selon le scope candidat retenu pendant l'audit, consulter en priorité les sources **officielles et actuelles** suivantes : ```text -REPRENDRE comme concept -REDESSINER selon KSP actuel -REPORTER vers ksp-program-api / ksp-program-lib / 0.3.2+ -REJETER +Documentation officielle Solana / Anza correspondant aux structures wire réellement ciblées +sources Agave / crates officielles actuelles lorsque leur comportement wire fait autorité +crates officielles d'interface Solana/Anza candidates à un réexport contrôlé +API actuelle de solana-pubkey déjà utilisée par Core +sources primaires des codecs candidats : borsh, wincode ou équivalent seulement si un besoin réel existe ``` -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 : +Pour toute crate candidate : ```text -InstructionDecoder -ProtocolDecoder -ProgramDecoder -Executor -TypedInstructionExecutor -Materializer -ProgramRegistry comportemental +vérifier version stable réellement courante +vérifier ownership/source officielle ou normative +vérifier MSRV/edition/features utiles si pertinents +vérifier default-features et features réellement nécessaires +inspecter dépendances transitives fondamentales +cargo tree -d +cargo tree -i si ajouté ``` -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. +L'exemple historique `solana-loader-v3-interface` dans l'architecture doit être **réaudité** s'il devient pertinent ; il n'est pas une dépendance obligatoire. De même, le rejet historique de `mpl-token-metadata` illustre une politique de contrôle du wire, pas une règle imposant son implémentation dans `0.2.13`. -### `ksp-program-lib` — hors scope +Aucun résultat externe ancien n'est considéré frais par défaut. -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 +## 5. État validé à préserver depuis `v0.2.12` -Le pipeline durable reste : +### 5.1 Workspace et Core + +État attendu : + +```text +workspace Rust 2024 stable +ksp-core-lib possède Error / ErrorCode / ErrorContext / Result +ksp-core-lib réexporte la Pubkey KSP +ksp-core-lib possède le registry des Program IDs fondamentaux +18 Program IDs fondamentaux couverts par les canaris actuels +ksp-interface-lib absent +ksp-program-api absent +``` + +`0.2.13` ne doit pas déplacer les Program IDs fondamentaux hors de Core. + +### 5.2 Transport + +Les transports on-chain sont déjà fonctionnels et séparés : + +```text +HTTP typed complet +WebSocket standard +Helius LaserStream WebSocket +Yellowstone gRPC standard/provider-neutral +``` + +Ils restent propriétaires de leurs DTOs réseau/provider et ne doivent pas acquérir une dépendance vers Interface/Program par commodité. + +Frontière durable : + +```text +Transport -X-> ksp-interface-lib sauf besoin architectural explicitement décidé plus tard +Transport -X-> ksp-program-api +Transport -X-> ksp-program-lib +``` + +`0.2.13` n'est pas une refactorisation générale de Transport. + +### 5.3 Off-chain, Wallet et Desks + +Les surfaces stabilisées jusqu'à `0.2.12` restent hors chantier : + +```text +ksp-offchain-transport-lib +ksp-wallet-lib +ksp-app-config-desk +ksp-app-wallet-desk +ksp-app-solprices-desk +``` + +Ne pas les modifier pour démontrer Interface, sauf si un gate de dépendance global révèle une violation préexistante directement bloquante et que le workflow impose une tranche dédiée. + +### 5.4 Pipeline durable + +Préserver : ```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. +Avec : -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. +```text +RAW -> CORE -X-> Program API +RAW -> CORE -X-> Program Lib +CORE -> DECODE peut utiliser Program API plus tard +``` + +Les modèles d'acquisition/replay/store ne sont pas la mission de `0.2.13`. + +--- + +## 6. Décisions acquises — ne pas redébattre sans contradiction réelle + +Les décisions suivantes sont considérées acquises : + +1. la crate cible s'appelle `ksp-interface-lib` ; +2. aucune crate `ksp-interface-api` séparée n'est créée par symétrie ; +3. `ksp-interface-lib` expose une API wire publique réutilisable par les implémentations officielles et externes ; +4. `ksp-interface-lib` ne dépend pas de `ksp-program-api` ni de `ksp-program-lib` ; +5. `ksp-program-api` est réservé à `0.2.14` ; +6. `ksp-program-lib` et les implémentations officielles concrètes sont reportés à des vertical slices ultérieures ; +7. Program IDs fondamentaux et `Pubkey` KSP restent possédés par Core ; +8. les codecs wire officiels utilisés directement par KSP appartiennent normalement à Interface ; +9. une crate protocolaire externe incompatible peut être remplacée par une implémentation KSP bornée ; +10. une extension Program externe peut temporairement posséder son propre wire lorsqu'Interface ne le possède pas encore ; +11. l'ancien `khadhroony-bot3` est une source d'idées, **jamais une autorité architecturale** ; +12. aucun monolithe équivalent à l'ancien `ks-lib` n'est recréé ; +13. la compatibilité automatique avec les anciens types kbot3 n'est pas un objectif ; +14. `0.3.2` reste propriétaire de l'extension Interface nécessaire aux acquisitions et à la normalisation CORE ; +15. une release concrète doit rester clôturable dans une seule session et être réduite si le sizing est négatif. + +Une contradiction avec la base stable réelle se traite par audit et décision documentée, pas par réécriture silencieuse de ces acquis. + +--- + +## 7. Questions réellement ouvertes à trancher pendant `pre.001` + +### 7.1 Premier périmètre wire concret + +Décider ce qui constitue réellement la **première surface** de `ksp-interface-lib` : + +```text +scaffold + primitives publiques uniquement +wire Program générique minimal +autre lot officiel minimal démontré par l'architecture +``` + +Ne pas forcer une famille de types parce qu'elle existait dans kbot3. + +### 7.2 Frontière Program-facing vs acquisition-facing + +Pour chaque candidat — instruction identity, CPI path, account meta, logs, return data, transaction failure, balance deltas, contexte de replay — décider explicitement : + +```text +nécessaire à Program API dès 0.2.14 +utile mais acquisition/CORE -> reporter 0.3.2+ +spécifique à un transport -> rester Transport +spécifique à un Program concret -> vertical slice ultérieure +``` + +### 7.3 Réutilisation Core vs nouveau wrapper + +Déterminer : + +```text +quand utiliser directement ksp_core_lib::Pubkey +quand créer un newtype KSP-owned +quand un simple alias serait insuffisant +quels identifiants ont déjà un owner canonique +``` + +Aucun wrapper ne doit être créé uniquement pour renommer un type stable déjà possédé par Core. + +### 7.4 Représentation des bytes et bornes + +Si la surface contient des données binaires : + +```text +Vec borné ? +newtype borné ? +encodage texte seulement à la frontière serde ? +limites maximales exactes ou conservatrices ? +validation avant allocation pathologique ? +Debug complet, résumé ou redacted/bounded ? +``` + +La décision doit être justifiée par le wire réel et les usages publics. + +### 7.5 Sérialisation et codecs + +Décider si `serde`, `borsh`, `wincode` ou autre est réellement requis dans `0.2.13`. + +Questions : + +```text +le contrat public a-t-il besoin d'un round-trip stable dès maintenant ? +le codec appartient-il au wire du protocole ou seulement à un stockage futur ? +une crate officielle actuelle peut-elle être réexportée/wrappée proprement ? +une réimplémentation KSP est-elle préférable à un graphe incompatible ? +``` + +Ne pas ajouter plusieurs codecs « pour préparer la suite ». + +### 7.6 Versionnement du contrat wire + +Ne pas introduire `format_version`, `contract_version` ou enum V1/V2 par réflexe. + +Si une version explicite est retenue, documenter : + +```text +ce qui est versionné +pourquoi l'évolution incompatible est plausible +qui choisit/interprète la version +comment unknown/future est traité +``` + +### 7.7 Error model et validation locale + +Décider quelles erreurs sont : + +```text +construction invalide +borne dépassée +wire malformed +unsupported local +invariant structurel +``` + +Utiliser l'Error KSP commun lorsque cela correspond au contrat actuel. Ne pas inventer une hiérarchie d'erreurs Program avant `ksp-program-api`. + +### 7.8 Surface d'extension externe + +Définir le canari minimum prouvant qu'une crate externe peut : + +```text +dépendre de ksp-interface-lib +importer uniquement les exports crate-root +construire/lire les types publics retenus +sérialiser/désérialiser si cette capacité fait partie du contrat +ne pas dépendre de modules privés ni de ksp-program-lib +``` + +### 7.9 Héritage kbot3 + +Pour les concepts historiques pertinents, produire une matrice : + +```text +REPRENDRE +REDESSINER +REPORTER +REJETER +``` + +Chaque ligne doit expliquer **pourquoi**, et vers quelle couche/version un report est effectué. + +### 7.10 Sizing + +Confirmer que le scope retenu tient dans une release/session. + +Si le premier wire officiel complet est trop large : + +```text +réduire 0.2.13 au socle public réellement nécessaire +reporter les familles additionnelles +ne pas ouvrir plusieurs protocoles en parallèle +``` + +--- + +## 8. Héritage `khadhroony-bot3` — audit historique contrôlé + +L'archive historique fournie avant la publication de `v0.2.12` est : + +```text +khadhroony-bot3_v0.5.3-pre.005-fix010.zip +``` + +Elle peut être redonnée dans la nouvelle session pour inspection complète. + +La reconnaissance préalable a identifié dans l'ancien `ks-lib` plusieurs familles d'idées : + +```text +identités et modèles wire +instruction path / contexte CPI +accounts résolus / instruction accounts +payload brut / return data / logs +état d'échec transaction +version de contrat + +contrats decoder historiques +identity / surfaces / coverage +recognize / outcome +diagnostics / proof +external decoder canaries + +contrats execution/materialization historiques +prepared execution plans +required signers / policy +materializer contracts +``` + +Deux leçons négatives sont déjà acquises : + +```text +ancien ks-lib = monolithe de plusieurs centaines de fichiers +plusieurs générations de Decoder API y coexistent +``` 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+`. +- ne copier aucun dossier/module entier ; +- ne conserver aucun nom historique uniquement pour compatibilité ; +- ne créer aucun trait Decoder/Executor/Materializer dans `0.2.13` ; +- ne considérer un type historique que si son **concept** répond à un besoin KSP actuel démontré ; +- comparer l'idée à l'architecture KSP avant de comparer le code ligne par ligne. -## 7. Dépendances et ownership +Si l'archive n'est pas disponible au démarrage, ne pas inventer ses détails. Utiliser seulement le seed ci-dessus et signaler les points nécessitant une nouvelle inspection opérateur. -`ksp-interface-lib` doit rester bas niveau et réutilisable. +--- -Baseline souhaitée à confronter au gate `pre.001` : +## 9. Objectifs et livrables de `0.2.13` + +Le scope exact est recalibré par `pre.001`, mais la release doit viser les livrables suivants. + +### 9.1 Crate et façade ```text -ksp-interface-lib -> ksp-core-lib +crates/ksp-interface-lib/ +Cargo.toml +src/lib.rs +README.md +USAGE.md +unit_tests/ +tests/ ``` -Ajouter seulement les crates de sérialisation/utilitaires réellement nécessaires et autorisées par les règles workspace. +La crate respecte les conventions workspace et n'expose pas ses modules privés comme API. -Interdictions initiales : +### 9.2 Surface wire publique + +Le lot retenu doit posséder : ```text +rustdoc public +constructeurs/validation explicites si nécessaires +invariants et bornes définis +ordre sémantique préservé +états optionnels fidèles au wire réel +Debug maîtrisé +serde/codec seulement si décidé +``` + +### 9.3 Dependency firewall + +Prouver au minimum : + +```text +Interface -> Core autorisé +Interface -X-> Program API +Interface -X-> Program Lib Interface -X-> Config -Interface -X-> Logging runtime Interface -X-> Transport -Interface -X-> Wallet Interface -X-> Store +Interface -X-> Wallet Interface -X-> Tauri -Interface -X-> reqwest / tonic / tokio runtime -Interface -X-> SDK/clients provider +Interface -X-> reqwest / tonic / runtime réseau ``` -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. +Une dépendance logging n'est ajoutée que si un comportement runtime réel à instrumenter existe ; une crate wire déclarative ne doit pas ajouter Logging par réflexe. -## 8. Qualités obligatoires de la première surface wire +### 9.4 Consumer externe -Toute surface retenue doit viser : +Créer un canari integration/downstream-style démontrant que la surface voulue est consommable uniquement via l'API publique. -- 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. +### 9.5 Documentation et validation -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. +`pre.001` doit créer : -## 9. Questions obligatoires de `pre.001` +```text +docs/plans/020-V0_2_13_INTERFACE_PLAN.md +docs/validation/016-V0_2_13_INTERFACE.md +``` -Avant d'écrire la surface définitive, répondre explicitement à ces questions : +Ces noms sont la suite documentaire attendue si la base stable ne contient pas déjà ces numéros. En cas de contradiction réelle, conserver la nomenclature effective de la base et documenter l'écart. -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` +## 10. Hors périmètre explicite -`pre.001` doit produire au minimum : +Ne pas implémenter dans `0.2.13` : -- 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é. +```text +ksp-program-api +ksp-program-lib +ProgramInstructionDecoder +ProgramAccountDecoder +ProgramEventDecoder +ProgramReturnDataDecoder +registry comportemental Program +recognition / coverage / decoder outcome définitifs +ProgramExecutionPreparer +PreparedProgramExecution définitif +materializer +execution policy +execution orchestration +System/SPL/Token-2022/Metadata/Anchor/DEX decoder concret +IDL parser/generator +Store/persistence RAW ou CORE +replay ledger / claims / jobs / workers +application Tauri +provider réseau +plugin dynamique / ABI C / WASM sandbox +compatibilité automatique avec ks-lib +migration des anciens modèles kbot3 +``` -`pre.001` peut rester principalement documentaire. Il ne doit pas créer une grosse API uniquement pour respecter le forecast initial ci-dessous. +Ne pas implémenter non plus un modèle complet : -## 11. Prévisions souples initiales +```text +RawBlock +CoreTransactionReplayInput +CoreInstructionReplayInput +pipeline acquisition universel +``` -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. +uniquement parce que ces structures pourront être utiles plus tard. Les wires génériques d'acquisition/CORE restent notamment attendus en `0.3.2`. + +--- + +## 11. Contraintes sécurité, API et architecture spécifiques + +### 11.1 Robustesse des données + +Toute donnée de taille variable doit avoir une politique explicite : + +```text +limite +moment de validation +allocation +conversion +Debug +serde +``` + +Rejeter avant allocation/copie pathologique lorsque techniquement possible. + +### 11.2 Fidélité wire + +Ne pas confondre : + +```text +absent +null / None lorsque le wire le permet +empty +zero +unknown/future +``` + +Ne pas normaliser une distinction wire utile pour simplifier l'API. + +### 11.3 Ordre + +Préserver l'ordre lorsque Solana lui donne une sémantique : + +```text +account metas +instruction accounts +instruction order +CPI path si retenu +``` + +Ne pas remplacer une séquence ordonnée par une map/set sans justification. + +### 11.4 Numeric safety + +Aucune vérité canonique lossless ne passe par `f32`/`f64`. + +Les slots, indexes, offsets, lengths et counts utilisent des types/bornes compatibles avec le wire réel et les conversions sont vérifiées. + +### 11.5 API évolutive + +Pour les enums publics susceptibles d'acquérir de nouvelles variantes externes, évaluer `#[non_exhaustive]` explicitement. + +Ne pas appliquer `#[non_exhaustive]` mécaniquement à chaque enum ; documenter le choix lorsqu'il affecte l'extensibilité downstream. + +### 11.6 Debug et données volumineuses + +Une structure contenant des bytes ou collections potentiellement importantes ne doit pas produire accidentellement un `Debug` gigantesque. + +Choisir selon le contrat : + +```text +Debug dérivé sûr et borné par construction +Debug custom résumant length/hash/metadata non sensible +pas de Debug public si inutile +``` + +### 11.7 Pas de comportement Program prématuré + +Une méthode passive de validation/codec/constructeur wire est autorisée lorsqu'elle appartient au contrat de données. + +Une méthode qui choisit : + +```text +quel decoder +si une instruction est reconnue +quelle sémantique canonique produire +comment matérialiser +comment exécuter +``` + +appartient aux couches Program/Materializer/Execution ultérieures. + +--- + +## 12. Première mission `0.2.13-pre.001` — gate obligatoire + +### 12.1 Baseline stable + +Avant toute modification lourde : + +```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 --workspace +``` + +Pour une base stable intacte, `cargo fmt --all` ne doit pas servir à introduire des modifications opportunistes. Si une commande modifie ou échoue sur la base stable, documenter le constat avant d'avancer. + +### 12.2 Audit interne complet + +Produire un inventaire concret : + +```text +Core public API utile +Program IDs / Pubkey ownership +DTOs Transport potentiellement ressemblants +règles wire/dependency +architecture 006 +roadmap 0.2.13 / 0.2.14 / 0.3.2 +workspace dependencies actuelles +``` + +Pour chaque type candidat déjà existant : + +```text +owner actuel +visibilité +consumer actuel +sémantique +raison éventuelle de réutiliser / laisser en place / redessiner +``` + +### 12.3 Audit kbot3 + +Si l'archive est disponible : + +1. inventorier uniquement les familles pertinentes ; +2. identifier les concepts, pas seulement les noms de fichiers ; +3. produire la matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` ; +4. distinguer clairement les idées Interface des idées Program API/Program Lib/Materializer/Execution ; +5. noter les anti-patterns historiques à ne pas reproduire. + +Ne pas porter de code pendant cette étape. + +### 12.4 Audit externe actuel + +Pour chaque dépendance/wire externe réellement candidat : + +```text +source primaire +version stable courante +contrat wire actuel +features requises +dépendances transitives +compatibilité avec solana-pubkey/Core actuel +codec generations +licence si nouvelle dépendance +``` + +Ne pas auditer vingt crates spéculatives : seulement les candidates du scope retenu. + +### 12.5 Matrice de frontières + +Produire une matrice explicite, au minimum : + +```text +concept/type +owner cible +0.2.13 ? +0.2.14 ? +0.3.2+ ? +source d'autorité +raison +``` + +Cette matrice doit empêcher la fuite entre : + +```text +Core +Interface +Transport +Program API +Program Lib +RAW/CORE +Store +``` + +### 12.6 Surface API proposée + +Avant implémentation, écrire conceptuellement la façade visée : + +```text +exports crate-root +principaux types publics +constructeurs +validation +serde/codec éventuel +erreurs +bornes +``` + +Les noms restent modifiables pendant `pre.001`; le but est de vérifier la cohérence, pas de figer prématurément tous les détails. + +### 12.7 Threat / robustness model + +Auditer : + +```text +oversized byte payload +oversized collection +integer overflow / index conversion +malformed wire +unknown enum/discriminant +nested structures pathologiques +Debug volumineux +allocation/copie excessive +serde hostile +panic/unwrap/expect +``` + +Pour chaque risque retenu, indiquer le test/canari prévu. + +### 12.8 Dependency graph cible + +Établir la cible réelle, par exemple : + +```text +ksp-interface-lib + -> ksp-core-lib + -> serde ? + -> codec(s) réellement retenu(s) ? + -> interface officielle compatible ? +``` + +et prouver explicitement les interdictions. + +Si une nouvelle dépendance externe est proposée, prévoir les `cargo tree` de validation. + +### 12.9 Stratégie de tests + +Décider avant le développement : + +```text +unit tests privés +integration public API +external consumer compile canary +round-trip fixtures +malformed fixtures +oversized/adversarial +compile-fail si utile +cargo tree/firewall +``` + +Aucun smoke réseau n'est requis par défaut pour une crate wire pure. + +### 12.10 Sizing + +Estimer chaque tranche intermédiaire avec le budget KSP d'environ **15–20 minutes de travail effectif** comme outil de découpage, jamais comme promesse. + +Si une tranche est manifestement trop grosse, la scinder avant implémentation. + +Si la release entière paraît impossible à clôturer raisonnablement dans la session, réduire le scope fonctionnel de `0.2.13` avant de coder. + +### 12.11 Documents de sortie + +Créer ou mettre à jour au minimum : + +```text +docs/plans/020-V0_2_13_INTERFACE_PLAN.md +docs/validation/016-V0_2_13_INTERFACE.md +deltas/0.2.13/pre.001.md +``` + +Le plan doit contenir la prévision souple recalibrée sous forme de headings `### pre.NNN`, avec statuts et éventuels fixes imbriqués conformément aux conventions KSP utilisées dans les releases récentes. + +### Critères de sortie de `pre.001` + +`pre.001` n'est fermé que si : + +```text +sources internes obligatoires réellement relues +base stable confirmée +surface Core/Transport pertinente inventoriée +architecture 006 confrontée à la base réelle +archive kbot3 auditée si disponible ou absence explicitement notée +matrice REPRENDRE/REDESSINER/REPORTER/REJETER produite +frontière 0.2.13 / 0.2.14 / 0.3.2 explicite +premier lot wire exact décidé ou réduit +ownership des types décidé +dépendances candidates auditables et bornées +threat/robustness model écrit +strategy de tests définie +dependency graph cible défini +plan + validation créés +forecast recalibré +sizing compatible avec une release/session +aucune implémentation Program lourde commencée +``` + +Si l'une de ces sorties reste ambiguë, `pre.001` continue ou reçoit un fix ; `pre.002` ne commence pas par défaut. + +--- + +## 13. Prévision souple initiale des prereleases + +Cette trajectoire est un **forecast de départ**. `pre.001` doit la fusionner, scinder, supprimer ou prolonger selon le scope réellement démontré. ### `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. +Lectures obligatoires, baseline, audit Core/Transport, audit kbot3, audit externe ciblé, matrice d'ownership, threat model, dependency graph, plan/validation et sizing. Aucun développement fonctionnel lourd. -### `pre.002` — Scaffold `ksp-interface-lib` + firewall +### `pre.002` — Scaffold `ksp-interface-lib` + façade + 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. +Créer la crate, l'ajouter au workspace, poser la façade publique minimale, README/USAGE initiaux et canaris de dépendances. Ne pas introduire encore une grande famille wire si le scaffold suffit pour fermer la tranche. -### `pre.003` — Primitives wire communes retenues +### `pre.003` — Primitives publiques 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. +Introduire uniquement les wrappers/identités/bornes réellement confirmés par `pre.001`, en réutilisant Core lorsque possible. Aucun modèle d'acquisition général par anticipation. -### `pre.004` — Wire instruction +### `pre.004` — Premier lot wire officiel retenu **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. +Matérialiser le premier lot fonctionnel réellement justifié : layouts/types/codec/constructeurs wire selon le plan final. Aucun decode sémantique. -### `pre.005` — Wire account/contexte complémentaire retenu +### `pre.005` — Second lot wire uniquement si démontré + +**Statut : optionnel** + +Ajouter une seconde famille uniquement si `pre.001` a démontré qu'elle appartient réellement à la foundation `0.2.13`. Supprimer cette tranche si le minimum est déjà complet. + +### `pre.006` — Sérialisation / bornes / adversarial **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. +Durcir round-trips, malformed/unknown, tailles hostiles, integer conversions, Debug, ordre et options. Si aucun codec n'est retenu, convertir cette tranche en hardening structurel pertinent plutôt que d'inventer de la sérialisation. -### `pre.006` — Sérialisation, bornes et adversarial +### `pre.007` — Consumer externe + API/dependency hardening **Statut : prévu** -Round-trips déterministes, malformed inputs, tailles/collections hostiles, représentation binaire, `Debug` sûr, ordre et états optionnels. +Prouver la consommation via crate-root, stabilité de la façade, firewall interne/externe, docs publiques et graphes Cargo. Aucun nouveau domaine wire opportuniste. -### `pre.007` — External consumer contract + API hardening +### `pre.008` — Gate technique final **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. +Gate workspace complet, canaris public API/dependencies, `cargo tree` pertinents et audit de complétude de la surface retenue. Aucun README/USAGE final ni préparation de publication dans cette tranche. -### `pre.008` — Gate technique et réconciliation documentaire finale +### `pre.009` — Réconciliation documentaire finale **Statut : prévu** -Workspace complet, Clippy/tests, audit public API/dependencies, README/USAGE/architecture/plan/validation. Aucune extension fonctionnelle opportuniste. +Réconcilier plan, validation, README/USAGE et architectures/références durables réellement affectées. Ne pas finaliser `CHANGELOG.md`, `ROADMAP.md` ni le prompt suivant. -### `pre.009` — Préparation de publication +### `pre.010` — Préparation de publication minimale **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. +Modifier fonctionnellement uniquement : + +```text +prompts/019-V0_2_14_START_PROMPT.md +CHANGELOG.md +ROADMAP.md +``` + +plus `Cargo.toml` et le delta mécanique requis. Aucun code, test, README, USAGE, plan, validation, règle ou architecture n'est rouvert. ### `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. +Passer la version Cargo à `0.2.13`, exécuter le gate de publication requis, créer le commit de livraison puis le tag stable `v0.2.13` conformément au workflow KSP. -## 12. Tests et canaris attendus - -Le plan final doit au moins prévoir : +Les responsabilités de fermeture restent donc séparées : ```text +gate technique final +réconciliation documentaire +préparation de publication minimale +rel.001 +``` + +Un `fix` reste strictement local à la responsabilité de sa tranche. + +--- + +## 14. Versionnement, deltas, commits, archives et tags + +Version Cargo des prereleases : + +```text +0.2.13-pre.1 +0.2.13-pre.2 +... +0.2.13-pre.N.fix.M +``` + +Deltas : + +```text +deltas/0.2.13/pre.001.md +deltas/0.2.13/pre.002.md +... +deltas/0.2.13/pre.NNN-fix.MMM.md +deltas/0.2.13/rel.001.md +``` + +Commits de livraison : + +```text +v0.2.13-pre.001 +v0.2.13-pre.002 +v0.2.13-pre.NNN-fix.MMM +v0.2.13-rel.001 +``` + +Aucun tag Git pour prerelease/fix/rel. + +Seule la release stable reçoit : + +```text +v0.2.13 +``` + +Archives : + +```text +ksp-general-.zip +ksp-doc-.zip lorsque le payload est strictement documentaire/prompts +``` + +Chaque archive contient uniquement les fichiers ajoutés/modifiés du delta plus son fichier delta. Les suppressions sont listées explicitement. + +Une prerelease non-fix synchronise `workspace.package.version` même si elle est documentaire. Un fix purement documentaire ne force pas de bump Cargo ; un fix code/build/runtime/config suit l'identifiant SemVer technique prévu par `VERSION_WORKFLOW.md`. + +Chaque delta est commité à partir de `0.1.x`; un fix ne réécrit jamais silencieusement le delta d'origine. + +--- + +## 15. Validation opérateur et procédure d'application + +Le mode opératoire reste celui des releases KSP récentes : + +1. l'assistant travaille à partir de la base opérateur réellement validée ; +2. il produit un delta ZIP minimal ; +3. l'opérateur applique l'archive dans son checkout ; +4. l'opérateur exécute les gates ; +5. les logs réels font autorité pour fermer la tranche ou produire un fix ; +6. un fix reste dans le scope exact de la tranche défectueuse. + +Gate Rust standard après modification : + +```bash cargo fmt --all python3 scripts/audit_rust_workspace_rules.py -python3 scripts/audit_markdown_tables.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 +``` + +Puis tests ciblés de la crate : + +```bash cargo test -p ksp-interface-lib +``` + +Aux gates globaux : + +```bash cargo test --workspace ``` -Canaris spécifiques attendus selon le scope retenu : +Lorsque le graphe change ou qu'une dépendance wire est ajoutée : -- 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. +```bash +cargo tree -p ksp-interface-lib --edges normal +cargo tree --duplicates +cargo tree -i si pertinent +``` -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. +Ne jamais déclarer PASS : -## 13. Hors scope explicite +```text +cargo fmt +rust audit +cargo check +clippy +tests +cargo tree +``` -Pour `0.2.13`, ne pas implémenter : +si la commande correspondante n'a pas réellement été exécutée. -- `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`. +Il n'y a **aucun gate Tauri** par défaut pour `0.2.13`, car la release ne doit modifier aucune application. -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. +Il n'y a **aucun smoke réseau** par défaut pour une crate wire pure. Si `pre.001` découvre un besoin réellement justifié, le gate doit être défini explicitement avant implémentation et ne doit pas transformer Interface en consumer réseau. -## 14. Discipline de delta et de session +--- -Pour chaque prerelease : +## 16. Tests et canaris attendus -- 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. +Le plan final doit couvrir, selon la surface retenue : -Les prévisions ci-dessus ne justifient jamais d'ajouter une surface qui n'est pas démontrée par l'audit. +### 16.1 Public API + +```text +exports crate-root complets +aucun pub mod opportuniste +rustdoc public +consumer externe compile +aucun import de module privé nécessaire +``` + +### 16.2 Dependency firewall + +```text +Interface -> Core seulement selon besoins réels +Interface -X-> Program API / Program Lib +Interface -X-> Config +Interface -X-> Transport +Interface -X-> Store +Interface -X-> Wallet +Interface -X-> Tauri +Interface -X-> reqwest / tonic / provider SDK +codec/direct protocol deps uniquement si possédés par le wire retenu +``` + +### 16.3 Wire fidelity + +Selon le contrat : + +```text +round-trip exact +fixtures officielles/externes lorsque disponibles +ordre préservé +unknown/malformed géré +absent/empty/value distingués +integer conversions vérifiées +no f64 canonical truth +``` + +### 16.4 Adversarial + +```text +oversized bytes +oversized collections +invalid discriminant +truncated input +trailing data si interdit par le wire +path/index overflow +nested/pathological input +Debug borné +``` + +### 16.5 Architecture + +Canaris empêchant l'introduction prématurée de : + +```text +Decoder trait +Program registry comportemental +Materializer trait +Execution preparer +Store DTO +Transport dependency +``` + +### 16.6 External consumer + +Le canari doit simuler une crate externe qui ne dépend pas de l'implémentation officielle Program et n'accède qu'à l'API publique Interface. + +--- + +## 17. Critères de clôture de `0.2.13` + +La release peut devenir stable seulement si : + +```text +ksp-interface-lib existe dans le workspace +scope public final correspond au plan recalibré de pre.001 +aucun trait Program n'a fuité dans Interface +aucun modèle RAW/CORE prématuré n'a été imposé +Program IDs fondamentaux restent dans Core +ownership de chaque type public est documenté +surface publique est consommable depuis crate externe +bornes/adversarial canaris verts +codec/serde éventuels sont justifiés et testés +dependency firewall vert +cargo tree pertinent inspecté si graphe modifié +cargo fmt + audit Rust + check + clippy verts +cargo test -p ksp-interface-lib vert +cargo test --workspace vert +aucun smoke réseau inventé sans besoin +README/USAGE finaux réconciliés dans la tranche documentaire dédiée +plan/validation/architecture durable réconciliés dans cette même tranche documentaire +prompt 0.2.14 finalisé seulement dans la dernière prerelease +CHANGELOG/ROADMAP finalisés seulement dans la dernière prerelease +aucun rattrapage code/doc dans rel.001 +``` + +Le numéro de prerelease prévu n'est jamais un critère de clôture. + +--- + +## 18. Release/session suivante envisagée + +La release suivante est : + +```text +0.2.14 — Program API foundation +``` + +Elle doit ouvrir `ksp-program-api` comme contrat **ouvert et extensible** pour les comportements Program réellement démontrés. + +Inputs historiques utiles à réauditer alors, notamment depuis kbot3 : + +```text +identity / descriptor +surfaces / capabilities +recognition +instruction/account decoder families +outcomes / diagnostics / proof +prepared execution boundary +external implementation canaries +``` + +Mais `0.2.13` ne doit pas figer leur forme trait avant cet audit. + +Après `0.2.14`, les implémentations officielles `ksp-program-lib` arrivent avec les vertical slices qui en ont réellement besoin, et non comme une grande couche monolithique préalable. + +La trajectoire RAW/CORE reste séparée : + +```text +0.3.1 Store RAW +0.3.2 extension Interface pour wires génériques acquisition/CORE +``` + +--- + +## 19. Instruction d'ouverture + +Au début de la session `0.2.13` : + +1. confirmer la base stable `v0.2.12` ou l'archive stable opérateur autoritaire ; +2. vérifier `workspace.package.version = 0.2.12` et `deltas/0.2.12/rel.001.md` ; +3. lire les règles de la section 3.1 dans l'ordre ; +4. lire l'architecture de la section 3.2, en particulier `006-WIRE_AND_PROGRAM.md` ; +5. relire la séquence fonctionnelle et la clôture `0.2.12` ; +6. exécuter la baseline complète avant développement lourd ; +7. inventorier la surface publique réelle Core et les DTOs Transport pertinents ; +8. réinspecter l'archive kbot3 si elle est disponible ; +9. produire la matrice `REPRENDRE / REDESSINER / REPORTER / REJETER` ; +10. auditer uniquement les sources externes réellement candidates et leurs versions actuelles ; +11. décider le premier minimum wire de `ksp-interface-lib` ; +12. produire la matrice d'ownership `Core / Interface / Transport / Program API / 0.3.2+` ; +13. décider bytes/bornes/serde/codec/versionnement/error model ; +14. produire la façade publique conceptuelle et le dependency graph cible ; +15. produire le threat/robustness model et la stratégie de tests ; +16. dimensionner la release et chaque tranche ; +17. créer le plan `020`, la validation `016` et `deltas/0.2.13/pre.001.md` ; +18. **ne pas commencer les traits Program, les decoders, les materializers, l'execution ou un modèle RAW/CORE complet avant la fermeture de ce gate**. + +La première réponse de travail de la nouvelle session doit donc être un **audit/sizing `0.2.13-pre.001` complet**, avec matrice d'héritage kbot3, frontières, surface wire proposée, dépendances, risques, tests et forecast recalibré — pas un scaffold déjà figé ni un portage de `ks-lib`.