Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.0.2

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-13 16:09:07 +02:00
parent 5f6c2ef45e
commit 199550bc82
25 changed files with 1233 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
deltas/0.0.2/pre.001-fix.001.md Normal file
View File

@@ -0,0 +1,94 @@
<!-- file: deltas/0.0.2/pre.001-fix.001.md -->
<!-- version: 2 -->
# Delta `0.0.2-pre.001-fix.001`
## Base requise
- dépôt KSP initialisé ;
- `0.0.1` commitée ;
- livraison `0.0.2-pre.001` appliquée ;
- prise en compte du `Cargo.toml` racine version 2 et du `.cargo/config.toml` version 1 fournis après la première livraison.
## Type de livraison
`ksp-general-0.0.2-pre.001-fix.001.zip`
## Objectif
Corriger la première proposition `0.0.2-pre.001` sans changer son périmètre : améliorer les contrats de fichiers, le README général, le formatage Rust, la politique MSRV, la documentation des crates, la version Cargo des correctifs et la réflexion sur l'organisation future des tests.
## Fichiers ajoutés
```text
.cargo/config.toml
deltas/0.0.2-pre.001-fix.001.md
```
## Fichiers modifiés
```text
Cargo.toml
README.md
clippy.toml
rustfmt.toml
docs/000-README.md
docs/rules/FILE_CONTRACTS.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/RULES_GENERAL.md
docs/rules/RULES_RUST.md
docs/rules/VERSION_WORKFLOW.md
```
## Fichiers supprimés
Aucun.
## Corrections et décisions incorporées
- le README racine décrit désormais le projet KSP lui-même et non la seule phase fondatrice ;
- la liste des prédécesseurs et la section d'état/version ont été retirées du README racine ;
- `DOC-ROOT-002` précise que le préfixe `000-` maintient `docs/000-README.md` en tête des listings et arbres lorsque la documentation devient volumineuse ;
- `DOC-CRATE-*` recommande `README.md`, `TODO.md` et particulièrement `USAGE.md` sans les imposer mécaniquement à toute crate ;
- aucun changelog par crate n'est prévu ;
- la structure exacte de `ROADMAP.md` et `CHANGELOG.md` reste à définir avant leur création ;
- `GEN-FILE-004` impose l'incrément de version à chaque enregistrement qui modifie le contenu d'un fichier, y compris lorsqu'une modification est ensuite annulée par une nouvelle modification ;
- `msrv = "1.85.0"` est retiré de `clippy.toml` ; KSP ne déclare actuellement aucun MSRV ;
- `rustfmt.toml` passe à `max_width = 160` et augmente les seuils associés afin que les autres limites explicites ne continuent pas à provoquer des retours proches de 80 caractères ;
- les tests unitaires doivent de préférence être séparés des fichiers de production et pourront être stockés sous `tests/unit/`, mais ils devront être explicitement rattachés au module testé pour conserver l'accès aux éléments privés ;
- la mécanique exacte de rattachement des tests unitaires externes reste à valider avant d'être imposée ;
- la version Cargo de ce correctif devient `0.0.2-pre.1.fix.1` afin que les commandes Cargo permettent d'identifier le correctif compilé ;
- le `Cargo.toml` racine conserve les métadonnées `license`, `authors` et `publish` fournies dans sa version 2 ;
- `.cargo/config.toml` est ajouté avec les chemins de build fournis.
## Validations exécutées
- parsing TOML de `Cargo.toml`, `.cargo/config.toml`, `clippy.toml` et `rustfmt.toml` ;
- validation syntaxique interne du format SemVer retenu pour `0.0.2-pre.1.fix.1` ;
- vérification des chemins et de la structure de l'archive ;
- vérification d'une fin de ligne finale unique pour chaque fichier texte livré ;
- vérification de l'absence de lockfile, cache, secret et sortie de compilation dans l'archive ;
- vérification documentaire du comportement Cargo des tests placés sous `tests/` ;
- vérification documentaire de la configuration `max_width` de rustfmt et du comportement MSRV de Clippy.
## Validations non exécutées
```bash
cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
```
L'environnement utilisé pour produire cette livraison ne fournit pas `cargo`. Ces commandes doivent être exécutées localement avant validation du correctif.
## Questions ouvertes
1. **Version Cargo et livraisons `ksp-doc-*`** — si `Cargo.toml` doit refléter absolument chaque identifiant de livraison, y compris une livraison strictement documentaire, alors une archive `ksp-doc-*` ne peut plus rester limitée à `docs/` et/ou aux prompts. Le contrat exact doit être tranché avant de généraliser la règle de synchronisation à toutes les livraisons.
2. **Tests unitaires séparés** — valider sur le premier vrai module Rust la mécanique permettant de conserver les fichiers sous `tests/unit/` tout en les compilant comme sous-modules unitaires avec accès au privé.
3. **Largeur rustfmt** — valider en pratique si les seuils `160/140/100/120` donnent le niveau de densité souhaité avant de les considérer définitivement stabilisés.
4. **Métadonnée Cargo `authors`** — elle est conservée parce qu'elle figure dans le `Cargo.toml` fourni, mais sa conservation à long terme reste à décider avant clôture de `0.0.2`.
## Application
Extraire l'archive depuis la racine du dépôt, puis exécuter les validations Cargo disponibles localement avant validation ou commit du correctif.

98
deltas/0.0.2/pre.001-fix.002.md Normal file
View File

@@ -0,0 +1,98 @@
<!-- file: deltas/0.0.2/pre.001-fix.002.md -->
<!-- version: 2 -->
# Delta 0.0.2-pre.001-fix.002
## Base requise
`0.0.2-pre.001` avec les corrections de `0.0.2-pre.001-fix.001`.
## Objectifs
- formaliser la règle de synchronisation sélective entre identifiant de delta et version Cargo ;
- distinguer la politique de commit de la phase fondatrice de celle applicable à partir de `0.1.x` ;
- expérimenter temporairement une séparation physique des tests unitaires hors de `src/` ;
- vérifier simultanément qu'un vrai test d'intégration n'utilise que l'API publique.
## Version Cargo
Cette livraison ajoute/modifie des fichiers `.rs`. Conformément à la règle proposée, le `Cargo.toml` racine passe donc à :
```text
0.0.2-pre.1.fix.2
```
La version Cargo correspond à la livraison `0.0.2-pre.001-fix.002`.
## Fichiers modifiés
- `Cargo.toml` ;
- `crates/ksp-core-lib/src/lib.rs` ;
- `docs/rules/FILE_CONTRACTS.md` ;
- `docs/rules/RULES_RUST.md` ;
- `docs/rules/VERSION_WORKFLOW.md`.
## Fichiers ajoutés temporairement
- `crates/ksp-core-lib/src/test_layout_probe.rs` ;
- `crates/ksp-core-lib/tests/unit/test_layout_probe.rs` ;
- `crates/ksp-core-lib/tests/public_api.rs`.
Ces trois fichiers, ainsi que les modifications de `lib.rs` associées, sont un banc d'essai et devront être retirés après décision sur la convention de tests.
## Expérience attendue
`src/test_layout_probe.rs` contient :
- une fonction publique temporaire réexportée au crate-root ;
- une fonction privée ;
- un module de test `#[cfg(test)]` dont la source physique est `tests/unit/test_layout_probe.rs`.
Le fichier `tests/unit/test_layout_probe.rs` doit :
- être exécuté dans la cible de tests unitaires de `ksp-core-lib` ;
- pouvoir appeler la fonction privée via `super::...` ;
- ne pas apparaître comme une cible d'intégration autonome.
Le fichier `tests/public_api.rs` doit :
- être compilé comme test d'intégration Cargo distinct ;
- utiliser seulement `ksp_core_lib::public_increment_probe` ;
- valider la façade publique de la crate.
## Commandes de validation demandées
```bash
cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
```
Pour confirmer précisément le découpage des tests, conserver aussi la sortie complète de :
```bash
cargo test -p ksp-core-lib
```
Le résultat recherché est une section `Running unittests ...` contenant le test privé, une cible `tests/public_api.rs` contenant le test public, et aucune cible autonome correspondant à `tests/unit/test_layout_probe.rs`.
## Critère de décision
- si cette structure fonctionne proprement avec Cargo, rustfmt, Clippy et les règles de visibilité KSP, elle pourra être généralisée après suppression du probe ;
- si elle échoue ou introduit une complexité disproportionnée, les tests unitaires resteront dans le module qu'ils testent ;
- dans les deux cas, les tests de l'API publique devront être placés en tests d'intégration lorsque cela est techniquement possible.
## Validations effectuées lors de la préparation
- reconstruction statique de la base `pre.001 + fix.001` ;
- vérification des chemins et versions de fichiers ;
- vérification TOML syntaxique avec Python pour les manifestes/configurations concernés.
## Validations non exécutées
Les commandes Cargo n'ont pas été exécutées dans l'environnement de préparation, qui ne fournit pas `cargo`/`rustc`. La validation décisive doit donc être réalisée dans le workspace KSP local.
## Temporaire
Cette livraison ne décide pas encore définitivement de la disposition des tests. Le code `test_layout_probe` est explicitement temporaire et doit disparaître après l'expérience.

144
deltas/0.0.2/pre.001-fix.003.md Normal file
View File

@@ -0,0 +1,144 @@
<!-- file: deltas/0.0.2/pre.001-fix.003.md -->
<!-- version: 1 -->
# Delta `0.0.2-pre.001-fix.003`
## Base requise
- dépôt KSP initialisé et `0.0.1` commitée ;
- `0.0.2-pre.001` appliquée ;
- correctifs `fix.001` et `fix.002` appliqués dans l'arbre de travail.
## Type de livraison
`ksp-general-0.0.2-pre.001-fix.003.zip`
## Objectifs
- valider définitivement la convention séparant tests unitaires et tests d'intégration ;
- retirer le code temporaire utilisé pour l'expérience de tests ;
- réorganiser les deltas sous `deltas/<X.Y.Z>/` ;
- généraliser la convention documentaire `000-`, `001-`, `002-` lorsqu'un ordre explicite est utile, sans l'appliquer à la racine du dépôt ;
- introduire `rel.NNN` comme marqueur de livraison d'une release finale, sans transformer ce marqueur en suffixe Cargo de la version finale.
## Version Cargo
Cette livraison supprime/modifie des sources Rust temporaires et modifie le `Cargo.toml` racine. Elle constitue donc un correctif technique :
```text
0.0.2-pre.1.fix.3
```
## Fichiers ajoutés
```text
deltas/0.0.2/pre.001.md
deltas/0.0.2/pre.001-fix.001.md
deltas/0.0.2/pre.001-fix.002.md
deltas/0.0.2/pre.001-fix.003.md
```
Les trois premiers fichiers sont les deltas historiques existants relocalisés sous la version cible `0.0.2`. Leur corps historique est conservé ; leur en-tête `file:` et leur version de fichier sont mis à jour pour refléter la relocalisation.
## Fichiers modifiés
```text
Cargo.toml
crates/ksp-core-lib/src/lib.rs
docs/000-README.md
docs/rules/FILE_CONTRACTS.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/RULES_RUST.md
docs/rules/VERSION_WORKFLOW.md
```
## Fichiers à supprimer
```text
crates/ksp-core-lib/src/test_layout_probe.rs
crates/ksp-core-lib/tests/public_api.rs
crates/ksp-core-lib/tests/unit/test_layout_probe.rs
deltas/0.0.2-pre.001.md
deltas/0.0.2-pre.001-fix.001.md
deltas/0.0.2-pre.001-fix.002.md
```
Les répertoires devenus vides sous `crates/ksp-core-lib/tests/` peuvent également être supprimés localement ; Git ne versionne pas les répertoires vides.
## Décisions validées
### Tests unitaires
L'expérience `fix.002` est concluante : le fichier de test unitaire séparé a été exécuté dans la cible `unittests` de `src/lib.rs`, a accédé à une fonction privée du module parent et n'a pas été découvert comme cible d'intégration autonome.
La convention KSP devient donc :
- `unit_tests/` à la racine de la crate pour les sources de tests unitaires séparées ;
- arborescence miroir de `src/` autant que possible ;
- rattachement explicite sous `#[cfg(test)]` au module testé ;
- usage de `unit_tests/` au maximum ;
- tests dans le module de production seulement en dernier recours justifié ;
- `tests/` réservé aux vrais tests d'intégration Cargo ;
- l'API publique pertinente doit être testée par intégration lorsque techniquement possible.
### Deltas
L'arbre canonique devient :
```text
deltas/
└── <X.Y.Z>/
├── pre.001.md
├── pre.001-fix.001.md
├── pre.002.md
└── rel.001.md
```
### Releases
Le marqueur `rel.NNN` appartient à l'identifiant de livraison et au nom du delta/archive. La version Cargo d'une release finale reste `X.Y.Z` sans `-rel.N`, afin de rester une version finale SemVer.
### Priorité documentaire
- `000-README.md` reste toujours le point d'entrée prioritaire d'un répertoire documentaire ordonné ;
- `001-`, `002-`, etc. peuvent exprimer un ordre de lecture/priorité lorsque cela apporte une valeur réelle ;
- tous les fichiers ne sont pas préfixés mécaniquement ;
- aucun préfixe numérique de ce type n'est appliqué aux fichiers situés à la racine du dépôt.
## Validations exécutées par le user sur `fix.002`
```bash
cargo fmt --all
cargo test --workspace
cargo test -p ksp-core-lib
cargo clippy --workspace --all-targets
```
Résultats communiqués :
- test unitaire séparé : `1 passed` ;
- test d'intégration public : `1 passed` ;
- doc-tests : succès, aucun test ;
- Clippy : terminé avec seulement les warnings attendus du probe temporaire (`dead_code` sur la fonction privée de production et `missing_docs` sur la crate de test d'intégration).
Ces warnings ne justifient aucun `allow` global et disparaissent avec le retrait du probe temporaire.
## Validations à exécuter après application de ce correctif
```bash
cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
```
Le résultat attendu après suppression du probe est un workspace minimal sans test temporaire et sans warning lié à cette expérience.
## Questions restant ouvertes
- structure exacte de `ROADMAP.md` ;
- structure exacte et cadence de `CHANGELOG.md` ;
- nomenclature formelle des environnements supportés par les applications de démonstration ;
- règle détaillée à appliquer si une livraison `rel.NNN` doit être corrigée avant son commit final.
Ces questions ne remettent pas en cause le squelette `0.0.2` ; elles doivent être closes pendant la planification fondatrice avant le prompt final ouvrant `0.1.x`.

108
deltas/0.0.2/pre.001-fix.004.md Normal file
View File

@@ -0,0 +1,108 @@
<!-- file: deltas/0.0.2/pre.001-fix.004.md -->
<!-- version: 1 -->
# Delta `0.0.2-pre.001-fix.004`
## Base requise
- dépôt KSP initialisé et `0.0.1` commitée ;
- `0.0.2-pre.001` appliquée ;
- correctifs `pre.001-fix.001` à `pre.001-fix.003` appliqués.
## Type de livraison
`ksp-general-0.0.2-pre.001-fix.004.zip`
## Objectifs
- introduire le `ROADMAP.md` général avec sa structure et ses statuts ;
- introduire `docs/IDEAS.md` pour conserver les pistes à explorer sans les transformer en engagements ;
- préciser la différence entre roadmap global et plan détaillé d'une version ;
- imposer qu'un plan établi en `pre.001` fournisse une prévision souple du découpage des prereleases de la version ;
- enregistrer la convention Git des commits versionnés et du tag stable `vX.Y.Z` ;
- préciser le traitement possible des correctifs d'une livraison `rel.NNN` avant publication stable.
## Version Cargo
Cette livraison ne modifie que des fichiers Markdown de documentation, de règles et de planification. Conformément à `VER-ID-008`, `workspace.package.version` n'est pas modifiée et reste celle du dernier correctif technique :
```text
0.0.2-pre.1.fix.3
```
## Fichiers ajoutés
```text
ROADMAP.md
docs/IDEAS.md
deltas/0.0.2/pre.001-fix.004.md
```
## Fichiers modifiés
```text
docs/000-README.md
docs/rules/FILE_CONTRACTS.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/VERSION_WORKFLOW.md
```
## Fichiers supprimés
Aucun.
## Décisions validées
### Roadmap
Chaque phase/version du roadmap peut contenir :
1. `Objectifs` : un ou plusieurs paragraphes décrivant l'état à atteindre ;
2. `Étapes` : grandes étapes avec cases `[ ]`, `[/]`, `[X]`, `[C]`, `[R]` ;
3. `Status` : bloc optionnel indiquant l'état global.
Légende canonique :
```text
[ ] prévu / non commencé
[/] en cours
[X] réalisé et validé
[C] annulé
[R] reporté
```
Le roadmap n'est pas obligé d'être organisé une ligne par prerelease.
### Planification de `pre.001`
La première prerelease d'une version produit ou révise un document de planification détaillant une prévision souple des prereleases de cette version. Le plan porte le découpage opérationnel plus fin que le roadmap et peut être réorganisé lorsque la réflexion ou le développement le justifie.
Le chemin et le nom canonique des futurs fichiers de planification pourront être fixés pendant la planification architecturale ; l'exigence de contenu est déjà normative.
### Idées
`docs/IDEAS.md` devient le registre des idées, pistes, alternatives et questions à conserver sans les considérer comme planifiées. Une idée retenue est transférée vers le roadmap, un plan, une règle ou une décision selon sa nature.
### Git et releases
- les commits de livraison utilisent le préfixe `v` suivi de l'identifiant de livraison ;
- les `pre`, `fix` et `rel` n'exigent pas de tag Git intermédiaire ;
- seul le commit considéré comme release stable reçoit le tag `vX.Y.Z` ;
- une livraison `rel.NNN` peut être corrigée avant le tag stable ; une release déjà publiée comme stable n'est normalement pas réécrite.
## Validations exécutées
Aucune commande Cargo n'est requise par ce correctif purement documentaire.
Contrôles de livraison à effectuer :
- vérifier l'emplacement et les en-têtes `file:` / `version:` ;
- vérifier l'absence de modification de `Cargo.toml` ;
- vérifier que le contenu du roadmap ne duplique pas les futurs plans détaillés de version.
## Questions restant ouvertes
- nom et emplacement canonique du document de planification créé/révisé en `pre.001` ;
- détails du plan global des crates, apps, workers et dépendances ;
- nomenclature définitive des interfaces et environnements d'applications/demos ;
- structure détaillée des premières phases `0.1.x`, `0.2.x`, etc.

113
deltas/0.0.2/pre.001.md Normal file
View File

@@ -0,0 +1,113 @@
<!-- file: deltas/0.0.2/pre.001.md -->
<!-- version: 2 -->
# Delta `0.0.2-pre.001`
## Base requise
- dépôt KSP initialisé ;
- version `0.0.1` validée et commitée ;
- `.gitignore` de `0.0.1` présent à la racine.
## Type de livraison
`ksp-general-0.0.2-pre.001.zip`
## Objectif
Proposer une première fondation `0.0.2` à corriger et valider, sans développement métier :
- README général de KSP ;
- workspace Cargo Rust 2024 minimal ;
- reprise initiale de `rustfmt.toml` et `clippy.toml` depuis `khadhroony-bot3` ;
- index normatif et premières règles générales, Rust, KSP, documentaires et de versionnement ;
- contrat initial des familles de fichiers ;
- création du premier squelette `ksp-core-lib`, nécessaire pour disposer d'un workspace Cargo possédant au moins un membre ;
- mise en place du système unique `deltas/`.
## Fichiers ajoutés
```text
Cargo.toml
README.md
RULES.md
clippy.toml
rustfmt.toml
crates/ksp-core-lib/Cargo.toml
crates/ksp-core-lib/src/lib.rs
docs/000-README.md
docs/rules/FILE_CONTRACTS.md
docs/rules/RULES_DOCUMENTATION.md
docs/rules/RULES_GENERAL.md
docs/rules/RULES_KSP.md
docs/rules/RULES_RUST.md
docs/rules/VERSION_WORKFLOW.md
deltas/0.0.2-pre.001.md
```
## Fichiers modifiés
Aucun fichier de la base `0.0.1` n'est modifié.
## Fichiers supprimés
Aucun.
## Décisions incorporées dans cette proposition
- aucun `rust-toolchain.toml` ;
- lockfiles volontairement non versionnés ;
- bibliothèques nommées `ksp-<role>-lib` ;
- applications nommées sous `ksp-app-*` ;
- workers nommés sous `ksp-worker-*` ;
- demos terminées par `-demo` ;
- crates directement sous `crates/` ;
- `docs/000-README.md` comme index documentaire ;
- un seul répertoire `deltas/` pour toutes les livraisons ;
- archives `ksp-general-*` et `ksp-doc-*` partageant le même identifiant de livraison ;
- un seul changelog général à terme, sans changelog par crate par défaut ;
- première crate squelette : `ksp-core-lib` ;
- future bibliothèque commune d'interface/wire : nom de travail `ksp-interface-lib` ;
- matérialisation séparée de la couche programmes/interfaces ;
- regroupement decoder/constructeur/exécution encore ouvert ;
- nomenclature initiale des environnements de demo : `mainnet`, `devnet`, `testnet`, `local-validator`, `synthetic`, absence de token = environnement sélectionnable.
## Validations exécutées
- vérification de la structure de l'archive ;
- parsing TOML des manifestes et configurations avec la bibliothèque standard Python ;
- vérification des fins de fichiers texte ;
- vérification de l'absence de `Cargo.lock`, lockfile Node, `target/`, secret ou artefact généré dans la livraison ;
- consultation de la documentation Cargo officielle concernant les workspaces virtuels et la nécessité d'au moins un membre.
## Validations non exécutées
- `cargo fmt --all` ;
- `cargo check --workspace` ;
- `cargo test --workspace` ;
- `cargo clippy --workspace --all-targets`.
Ces commandes n'ont pas pu être exécutées dans l'environnement de production de cette livraison car l'exécutable `cargo` n'y est pas disponible. Elles doivent être exécutées après extraction avant validation de la prerelease.
## Points à corriger ou valider
1. Valider la distinction entre version Cargo `0.0.2-pre.1` et identifiant de livraison `0.0.2-pre.001`.
2. Valider ou modifier le `msrv = "1.85.0"` repris de `khadhroony-bot3` dans `clippy.toml`.
3. Valider la nomenclature des environnements de demo, notamment le token `local-validator`.
4. Valider le nom provisoire `ksp-interface-lib` pour la future crate commune wire/interface.
5. Valider si `ksp-core-lib` doit rester strictement vide fonctionnellement jusqu'à la phase architecturale suivante.
6. Vérifier si les règles Rust reprises sont complètes ou si certaines règles de `khadhroony-bot3` doivent être supprimées, reformulées ou déplacées vers une portée KSP spécifique.
7. Vérifier le niveau de détail attendu de `FILE_CONTRACTS.md` avant d'étendre le catalogue aux futurs fichiers.
## Application
Extraire l'archive depuis la racine du dépôt `khadhroony-solana-project`, puis exécuter :
```bash
cargo fmt --all
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets
```
Ne pas commiter la prerelease avant correction des points refusés et validation des commandes disponibles localement.