khadhroony-solana-project/docs/rules/RULES_KSP.md

<!-- file: docs/rules/RULES_KSP.md -->
<!-- version: 1 -->

# Règles spécifiques à KSP

## Portée

Les règles `KSP-*` s'appliquent à l'architecture, la nomenclature et l'organisation propres à `khadhroony-solana-project`.

## Succession des projets précédents

- **KSP-LINEAGE-001** — KSP succède aux projets Khadhroony Solana précédents mais ne les duplique pas mécaniquement.
- **KSP-LINEAGE-002** — Une reprise de code, structure, dépendance ou documentation historique doit être justifiée par un besoin KSP actuel.
- **KSP-LINEAGE-003** — Une architecture historique n'est jamais considérée comme normative uniquement parce qu'elle a fonctionné dans `khadhroony-bot3` ou un prédécesseur.

## Nomenclature des crates et exécutables

- **KSP-NAME-001** — Une bibliothèque Rust réutilisable se nomme `ksp-<role>-lib`.
- **KSP-NAME-002** — Une application se nomme `ksp-app-<role>-<interface>` lorsque l'interface doit être indiquée.
- **KSP-NAME-003** — Un worker se nomme `ksp-worker-<role>`.
- **KSP-NAME-004** — Une démonstration se termine par `-demo`.
- **KSP-NAME-005** — Les interfaces d'application utilisent des tokens courts et stables, notamment `cli` pour une interface en ligne de commande et `desk` pour une application desktop.
- **KSP-NAME-006** — Les crates Rust sont placées directement sous `crates/` ; aucun sous-répertoire de catégories n'est utilisé pour les regrouper.
- **KSP-NAME-007** — Les applications sont placées sous `apps/` lorsqu'elles sont introduites.

## Environnements des démonstrations

- **KSP-DEMO-001** — Une demo limitée à un environnement encode explicitement cet environnement dans son nom avant le token d'interface et avant `-demo`.
- **KSP-DEMO-002** — Les tokens d'environnement initiaux sont `mainnet`, `devnet`, `testnet`, `local-validator` et `synthetic`.
- **KSP-DEMO-003** — Une demo sans token d'environnement est conçue pour permettre le choix de l'environnement parmi ceux qu'elle supporte ; l'absence de token ne signifie pas implicitement `mainnet`.
- **KSP-DEMO-004** — Exemples de forme : `ksp-app-<role>-devnet-cli-demo`, `ksp-app-<role>-local-validator-desk-demo`, `ksp-app-<role>-synthetic-cli-demo` et `ksp-app-<role>-desk-demo` pour une demo à environnement sélectionnable.
- **KSP-DEMO-005** — Une demo ne doit pas agréger plusieurs responsabilités indépendantes uniquement pour constituer une application de démonstration universelle.

## Frontières architecturales déjà décidées

- **KSP-ARCH-001** — `ksp-core-lib` regroupe les fondations réellement transversales, y compris la responsabilité autrefois séparée des identifiants de programmes ; il ne doit pas devenir un conteneur générique de tout code partagé.
- **KSP-ARCH-002** — Une bibliothèque commune dédiée aux interfaces/wire on-chain doit exister ; son nom de travail est `ksp-interface-lib` jusqu'à validation définitive.
- **KSP-ARCH-003** — La matérialisation constitue une responsabilité distincte des interfaces/wire et du traitement des programmes.
- **KSP-ARCH-004** — Le regroupement ou la séparation définitive du decoder, de la construction d'instructions et de l'exécution réseau reste une décision d'architecture ouverte ; aucune structure historique ne doit être recopiée avant cette décision.
- **KSP-ARCH-005** — Une bibliothèque comme le wallet reste indépendante de son interface utilisateur ; les applications et demos qui la manipulent consomment la bibliothèque au lieu d'y être intégrées.
- **KSP-ARCH-006** — La configuration doit disposer d'une bibliothèque propriétaire de ses contrats et pourra disposer d'une application dédiée à l'inspection et la modification des profils et valeurs autorisées.

## Dépendances et outils

- **KSP-TOOL-001** — Aucun `rust-toolchain.toml` n'est utilisé dans KSP.
- **KSP-TOOL-002** — Les lockfiles de dépendances sont ignorés et non livrés.
- **KSP-TOOL-003** — Les répertoires et fichiers générés ne sont ajoutés au `.gitignore` qu'après apparition d'un besoin réel et décision explicite ; les futurs `bindings/` et `gen/` Tauri seront traités à ce moment.