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

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 :

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 :

0.2.13 — Interface foundation

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.

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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.