Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.12-pre.011

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-27 19:39:20 +02:00
parent 4f71dbc62d
commit e701267135
5 changed files with 522 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

403
prompts/018-V0_2_13_START_PROMPT.md Normal file
View File

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