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

<!-- file: prompts/001-V0_1_1_START_PROMPT.md -->
<!-- version: 2 -->

# Prompt de démarrage KSP 0.1.1

**Status : Final — à utiliser après validation et publication stable de `0.0.3`.**

## 1. Identité

Release fonctionnelle :

```text
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 :

```text
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.

La session ne doit commencer que depuis la release stable/taguée `v0.0.3`.

## 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 :

```text
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` :

```text
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 :

```text
v0.1.1
```

## 12. Dimensionnement indicatif

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

Trajectoire candidate uniquement :

```text
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 :

```bash
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 :

```text
0.1.2 — ksp-logging-lib
```