khadhroony-solana-project/prompts/018-V0_2_13_START_PROMPT.md

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