khadhroony-solana-project/prompts/001-V0_1_1_START_PROMPT.md

Prompt de démarrage KSP 0.1.1

Status : Quasi-final — à confirmer pendant la clôture 0.0.3-pre.010.

1. Identité

Release fonctionnelle :

0.1.1 — Core foundation

Première release fonctionnelle de Khadhroony Solana Project.

2. Mission

Implémenter et stabiliser ksp-core-lib comme fondation N1 minimale, générale et durable.

Cette release doit fournir uniquement les contrats réellement transversaux requis par les couches suivantes, en particulier le contrat commun d'erreur et les Program IDs fondamentaux.

Elle ne doit pas ouvrir prématurément Logging, Config, Wallet, Transport, Program decoding/execution, Store ou les autres couches supérieures.

3. Base requise

Base attendue :

0.0.3 stable

Avant tout travail :

• vérifier que la fondation 0.0.3 est validée ;
• vérifier le working tree Git ;
• relire le delta final 0.0.3 et le prompt présent ;
• vérifier que la version workspace est passée à la version/prerelease 0.1.1 appropriée au premier delta.

0.0.3-pre.010 doit confirmer les références exactes de clôture.

4. Sources de vérité

Relire en priorité les fichiers réellement présents dans la base, notamment :

• ROADMAP.md ;
• docs/plans/001-V0_0_3_PLAN.md ;
• docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.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/rules/RULES_DEPENDENCIES.md ;
• docs/rules/RULES_KSP.md ;
• docs/IDEAS.md.

Relire également les règles/index racine supplémentaires présents dans le dépôt au moment de la session.

Ne jamais inventer un document absent de la base de travail.

5. Première prerelease obligatoire : 0.1.1-pre.001

pre.001 est d'abord une prerelease de brainstorming, audit et planification.

Elle doit :

1. inventorier le contenu réel actuel de ksp-core-lib ;
2. identifier les contrats N1 réellement nécessaires à 0.1.1 ;
3. concevoir le contrat Error / Result commun sans faire connaître à Core tous les futurs domaines ;
4. inventorier les Program IDs fondamentaux qui appartiennent réellement à Core ;
5. identifier les primitives communes justifiées maintenant ;
6. vérifier depuis les sources officielles actuelles les crates Solana/Anza nécessaires avant toute sélection de version ;
7. éviter d'ajouter une dépendance simplement parce qu'elle est autorisée architecturalement ;
8. proposer l'API publique et les crate-root reexports ;
9. proposer la stratégie de tests ;
10. dimensionner les prereleases suivantes ;
11. confirmer explicitement les hors-scope.

Ne pas transformer pre.001 en une grosse phase de développement avant que ce plan soit validé.

6. Périmètre fonctionnel candidat

Error / Result

La direction acquise est un type public commun :

ksp_core_lib::Error

et un alias Result<T> ou forme équivalente à confirmer.

Le design doit :

• être utilisable par les crates KSP supérieures ;
• permettre catégorie/code/contexte ou autre extension propre ;
• éviter que Core possède une enum fermée de toutes les erreurs futures du projet ;
• conserver des conversions/causes utiles sans créer de dépendances vers les domaines supérieurs ;
• respecter les règles no unwrap, no expect, no panic production et no ?.

Le modèle exact doit être décidé pendant pre.001, pas supposé par ce prompt.

Program IDs fondamentaux

Les Program IDs fondamentaux sont une responsabilité de ksp-core-lib.

Le pre.001 doit définir lesquels sont réellement nécessaires dans la première surface Core et comment ils sont exposés.

La représentation doit privilégier les primitives officielles Solana/Anza actuelles lorsque leur stabilité et leur API sont appropriées.

Primitives communes

N'ajouter que les primitives dont un usage concret existe dans Core.

Ne pas faire de ksp-core-lib un fourre-tout pour :

• wallet/signing ;
• codecs wire ;
• RPC ;
• persistence ;
• Program decoding ;
• materialization ;
• configuration ;
• logging.

7. Dépendances

Core reste en bas du graphe KSP.

Interdictions pour 0.1.1 :

ksp-core-lib -X-> ksp-logging-lib
ksp-core-lib -X-> ksp-config-lib
ksp-core-lib -X-> ksp-wallet-lib
ksp-core-lib -X-> ksp-interface-lib
ksp-core-lib -X-> ksp-program-api
ksp-core-lib -X-> ksp-store-api
ksp-core-lib -X-> transport/workers/jobs/apps

Les primitives officielles Solana/Anza autorisées architecturalement ne sont ajoutées que si un item Core réel les nécessite.

solana-pubkey est un candidat naturel si les Program IDs sont représentés avec Pubkey, mais sa version et son usage doivent être vérifiés dans pre.001.

8. Hors scope strict de 0.1.1

• ksp-logging-lib ;
• ksp-config-lib ;
• toute application Tauri ;
• wallet/keypair/signer management ;
• wire codecs Borsh/Wincode ;
• ksp-interface-lib ;
• Program decoder/registry/ProgramExecutionPreparer ;
• execution policy/orchestration ;
• RPC/WS/Helius/Yellowstone ;
• Store/PostgreSQL ;
• materializers ;
• workers/jobs/pipelines ;
• scenarios ;
• trading/ML.

Un contrat minimal appartenant réellement à Core peut être ajouté si le pre.001 démontre qu'il est nécessaire, mais il ne doit pas servir de prétexte pour ouvrir un domaine supérieur.

9. Règles Rust importantes

Préserver notamment :

• Rust 2024 ;
• async-first pour les I/O futures, sans inventer de async lorsqu'aucune I/O n'existe ;
• unsafe interdit ;
• unwrap / expect interdits ;
• panic interdit en production ;
• opérateur ? interdit ;
• returns explicites selon les règles workspace ;
• unreachable_pub = deny ;
• missing_docs = warn ;
• imports de traits seulement lorsque nécessaire, sinon chemins pleinement qualifiés selon les règles du projet ;
• API publique via réexports crate-root explicites ;
• pas de mod.rs ;
• pas de pub(super) / pub(in ...) ;
• documentation code/Rustdoc en anglais ;
• règles de format/EOF du projet.

Les tests unitaires doivent suivre la convention de fichiers externes au src lorsqu'elle est applicable dans la base réelle.

10. Dépendances externes

Avant d'ajouter ou modifier une crate Solana/Anza :

• consulter les sources officielles actuelles ;
• privilégier les générations récentes compatibles ;
• vérifier le graphe de dépendances pertinent ;
• ne pas conserver une génération ancienne pour compatibilité avec une crate protocolaire remplaçable.

0.1.1 n'introduit aucun codec wire par anticipation.

11. Git et deltas

À partir de 0.1.x, chaque delta est commité.

Cela inclut :

• pre.NNN ;
• pre.NNN-fix.NNN ;
• autres deltas intermédiaires.

Une étape erronée est corrigée par un commit/delta suivant ; ne pas réécrire l'historique pour la faire disparaître.

Seul le commit stable final reçoit le tag :

v0.1.1

12. Dimensionnement indicatif

Le nombre réel de prereleases est décidé dans pre.001.

Trajectoire candidate uniquement :

pre.001  audit + brainstorming + plan
pre.002  Error/Result et fondation API
pre.003  Program IDs/primitives retenues
pre.004  compléments/tests/audits
pre.005  validation finale/docs/cleanup/prompt 0.1.2

Scinder une prerelease si son périmètre devient trop large.

13. Validations attendues

Lorsque le code concerné existe et que les commandes sont applicables :

cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets

Exécuter aussi les audits/scripts du dépôt réellement présents et applicables.

Aucune validation non exécutée ne doit être déclarée réussie.

14. Clôture de 0.1.1

La dernière prerelease doit :

• exécuter les validations finales ;
• corriger documentation et règles devenues obsolètes ;
• nettoyer/archiver les éléments temporaires ;
• mettre à jour le changelog selon les conventions du dépôt ;
• produire le prompt de démarrage 0.1.2 ;
• confirmer la version stable ;
• préparer le commit/tag v0.1.1.

La release suivante prévue est :

0.1.2 — ksp-logging-lib