v0.1.1-pre.005
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 23
|
||||
# version: 24
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-core-lib"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.1.1-pre.4"
|
||||
version = "0.1.1-pre.5"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
191
deltas/0.1.1/pre.005.md
Normal file
191
deltas/0.1.1/pre.005.md
Normal file
@@ -0,0 +1,191 @@
|
||||
<!-- file: deltas/0.1.1/pre.005.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.1.1-pre.005` — clôture Core et prompt Logging
|
||||
|
||||
## Base requise
|
||||
|
||||
`v0.1.1-pre.004` au sens du commit de livraison correspondant, avec :
|
||||
|
||||
```text
|
||||
workspace.package.version = "0.1.1-pre.4"
|
||||
```
|
||||
|
||||
Le présent delta ouvre :
|
||||
|
||||
```text
|
||||
workspace.package.version = "0.1.1-pre.5"
|
||||
```
|
||||
|
||||
## Objectif
|
||||
|
||||
Clôturer la phase de développement `0.1.1` sans élargir la surface Core : enregistrer les validations finales de `pre.004`, confirmer la politique de features `solana-pubkey`, réaligner les documents de référence et produire le prompt final de démarrage `0.1.2`.
|
||||
|
||||
La publication stable reste un delta `0.1.1-rel.001` séparé après validation de cette prerelease.
|
||||
|
||||
## Validation de la base précédente
|
||||
|
||||
Le user a exécuté avec succès le 2026-08-14 :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo tree -p ksp-core-lib
|
||||
cargo tree -p ksp-core-lib -d
|
||||
cargo tree -p ksp-core-lib -e features
|
||||
```
|
||||
|
||||
Résultats communiqués :
|
||||
|
||||
- 14 tests unitaires passent ;
|
||||
- 3 tests d'intégration publics passent ;
|
||||
- Clippy passe sans warning communiqué ;
|
||||
- `cargo tree` conserve `solana-pubkey 4.3.0` comme unique dépendance externe directe de `ksp-core-lib` ;
|
||||
- `solana-pubkey` résout `solana-address 2.7.0` puis ses dépendances fondamentales ;
|
||||
- `cargo tree -d` ne rapporte aucun doublon ;
|
||||
- `cargo tree -e features` a été inspecté.
|
||||
|
||||
## Décision finale sur les features `solana-pubkey`
|
||||
|
||||
Aucune feature optionnelle supplémentaire n'est activée dans `0.1.1`.
|
||||
|
||||
La déclaration workspace reste :
|
||||
|
||||
```toml
|
||||
solana-pubkey = { version = "^4.3", default-features = false }
|
||||
```
|
||||
|
||||
Les features optionnelles `alloc`, `borsh`, `bytemuck`, `curve25519`, `rand`, `serde`, `sha2`, `std` et `wincode` ne correspondent à aucun besoin du contrat Core actuellement livré.
|
||||
|
||||
Les features `solana-address` visibles dans le graphe résolu (`copy`, `decode`, `error`, `sanitize`, `syscalls`, `default`) appartiennent à la composition interne de la génération actuelle de `solana-pubkey`/`solana-address`. Elles ne justifient pas une activation KSP supplémentaire.
|
||||
|
||||
Les futures releases activent une feature uniquement lorsque leur propriétaire fonctionnel démontre un besoin concret. En particulier, `borsh`/`wincode` ne sont pas activées dans Core par anticipation d'une future surface wire.
|
||||
|
||||
## Documentation finale
|
||||
|
||||
Le plan `0.1.1` est consolidé pour :
|
||||
|
||||
- refléter la surface réellement implémentée ;
|
||||
- enregistrer les validations réussies de `pre.004` ;
|
||||
- fermer la question des features `solana-pubkey` ;
|
||||
- confirmer qu'aucune primitive N1 supplémentaire n'est nécessaire ;
|
||||
- confirmer qu'aucun `README.md`/`USAGE.md` spécifique à la crate n'est nécessaire pour cette petite surface ;
|
||||
- confirmer que le dépôt ne possède actuellement aucun changelog général à synchroniser.
|
||||
|
||||
La séquence fonctionnelle est mise à jour pour remplacer le périmètre candidat de `0.1.1` par la surface effectivement stabilisée et son lifecycle réellement suivi.
|
||||
|
||||
Les index de documentation/plans/prompts sont réalignés avec les fichiers présents.
|
||||
|
||||
## Prompt `0.1.2`
|
||||
|
||||
Ajout :
|
||||
|
||||
```text
|
||||
prompts/002-V0_1_2_START_PROMPT.md
|
||||
```
|
||||
|
||||
Ce prompt ouvre :
|
||||
|
||||
```text
|
||||
0.1.2 — Logging foundation
|
||||
```
|
||||
|
||||
après publication stable de `0.1.1`.
|
||||
|
||||
Il conserve notamment les décisions suivantes :
|
||||
|
||||
- `ksp-logging-lib` est la façade KSP unique de logging/tracing runtime ;
|
||||
- Logging peut dépendre de `ksp-core-lib`, jamais l'inverse ;
|
||||
- `pre.001` de Logging reste une phase d'audit/brainstorming/planification ;
|
||||
- la stack `tracing` et ses features sont revérifiées depuis les sources officielles avant ajout ;
|
||||
- l'API doit préserver les callsites réels ;
|
||||
- Logging possède ses settings runtime sans dépendre de Config ;
|
||||
- les secrets ne sont jamais loggés automatiquement ;
|
||||
- les dépendances externes restent centralisées sous `[workspace.dependencies]`.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
```text
|
||||
deltas/0.1.1/pre.005.md
|
||||
prompts/002-V0_1_2_START_PROMPT.md
|
||||
```
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
docs/000-README.md
|
||||
docs/plans/000-README.md
|
||||
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||
docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md
|
||||
prompts/000-README.md
|
||||
```
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun.
|
||||
|
||||
## Nettoyage/archivage
|
||||
|
||||
Aucun fichier temporaire ou obsolète supplémentaire n'est identifié comme devant être supprimé dans cette tranche.
|
||||
|
||||
Les deltas historiques et le prompt `0.1.1` restent conservés comme historique utile.
|
||||
|
||||
## Validations exécutées pendant la préparation
|
||||
|
||||
Contrôles statiques hors Cargo :
|
||||
|
||||
- parsing TOML ;
|
||||
- headers `file:` / `version:` des fichiers modifiés/ajoutés ;
|
||||
- terminaison EOF ;
|
||||
- liens Markdown locaux ;
|
||||
- cohérence des index documentaires ;
|
||||
- cohérence de la version `0.1.1-pre.5` ;
|
||||
- absence d'ajout de feature `solana-pubkey` ;
|
||||
- intégrité de l'archive delta.
|
||||
|
||||
## Validations non exécutées pendant la préparation
|
||||
|
||||
L'environnement de préparation ne fournit pas `cargo`/`rustc`.
|
||||
|
||||
Après application du delta, exécuter sur le dépôt cible :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo tree -p ksp-core-lib
|
||||
cargo tree -p ksp-core-lib -d
|
||||
cargo tree -p ksp-core-lib -e features
|
||||
```
|
||||
|
||||
Aucune de ces validations de `pre.005` n'est déclarée réussie avant exécution par le user.
|
||||
|
||||
## Publication suivante
|
||||
|
||||
Si `pre.005` est propre, préparer :
|
||||
|
||||
```text
|
||||
0.1.1-rel.001
|
||||
```
|
||||
|
||||
avec :
|
||||
|
||||
```text
|
||||
workspace.package.version = "0.1.1"
|
||||
```
|
||||
|
||||
Le commit de `rel.001` validé comme stable reçoit ensuite le tag :
|
||||
|
||||
```text
|
||||
v0.1.1
|
||||
```
|
||||
|
||||
La session suivante peut alors démarrer avec :
|
||||
|
||||
```text
|
||||
prompts/002-V0_1_2_START_PROMPT.md
|
||||
```
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/000-README.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Documentation KSP
|
||||
|
||||
@@ -34,7 +34,8 @@ docs/
|
||||
├── plans/
|
||||
│ ├── 000-README.md
|
||||
│ ├── 001-V0_0_3_PLAN.md
|
||||
│ └── 002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||
│ ├── 002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||
│ └── 003-V0_1_1_CORE_FOUNDATION_PLAN.md
|
||||
└── rules/
|
||||
├── FILE_CONTRACTS.md
|
||||
├── PROMPT_STRUCTURE.md
|
||||
@@ -51,7 +52,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é
|
||||
|
||||
## Documents de planification
|
||||
|
||||
Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md).
|
||||
Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la première release fonctionnelle est conservé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md).
|
||||
|
||||
`IDEAS.md` conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/000-README.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Plans KSP
|
||||
|
||||
@@ -10,8 +10,8 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
|
||||
## Plans de référence
|
||||
|
||||
- [`001-V0_0_3_PLAN.md`](001-V0_0_3_PLAN.md) — plan historique de la phase fondatrice `0.0.3`, clôturée ;
|
||||
- [`002-FUNCTIONAL_RELEASE_SEQUENCE.md`](002-FUNCTIONAL_RELEASE_SEQUENCE.md) — séquence active de référence des premières releases fonctionnelles, dont `0.1.1`.
|
||||
- [`003-V0_1_1_CORE_FOUNDATION_PLAN.md`](003-V0_1_1_CORE_FOUNDATION_PLAN.md) — plan actif détaillé de `0.1.1`, établi par `0.1.1-pre.001`.
|
||||
- [`002-FUNCTIONAL_RELEASE_SEQUENCE.md`](002-FUNCTIONAL_RELEASE_SEQUENCE.md) — séquence active de référence des premières releases fonctionnelles ;
|
||||
- [`003-V0_1_1_CORE_FOUNDATION_PLAN.md`](003-V0_1_1_CORE_FOUNDATION_PLAN.md) — plan détaillé de `0.1.1`, établi par `0.1.1-pre.001` et consolidé jusqu'à sa tranche de clôture.
|
||||
|
||||
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Séquence des releases fonctionnelles KSP
|
||||
|
||||
@@ -48,27 +48,24 @@ Stabiliser `ksp-core-lib` comme fondation N1 minimale et durable.
|
||||
|
||||
Le Core possède uniquement les contrats réellement transversaux nécessaires aux couches supérieures.
|
||||
|
||||
### Périmètre initial
|
||||
### Surface stabilisée
|
||||
|
||||
À auditer précisément dans `0.1.1-pre.001`, avec comme candidats acquis :
|
||||
`0.1.1` stabilise :
|
||||
|
||||
- type public commun `ksp_core_lib::Error` ;
|
||||
- alias public commun `Result<T>` ou forme équivalente validée ;
|
||||
- architecture d'erreur permettant aux domaines supérieurs d'ajouter du contexte sans faire connaître tous les futurs domaines à Core ;
|
||||
- Program IDs fondamentaux appartenant à KSP Core ;
|
||||
- primitives/identités réellement communes et déjà justifiées ;
|
||||
- conventions de version/provenance N1 uniquement si un besoin concret existe ;
|
||||
- exports crate-root et documentation publique ;
|
||||
- tests unitaires/integration appropriés ;
|
||||
- respect complet des règles Rust/workspace.
|
||||
- `ksp_core_lib::ErrorCode`, `ErrorContext`, `Error` et `Result<T>` comme contrat d'erreur ouvert aux domaines supérieurs ;
|
||||
- `ksp_core_lib::Pubkey` comme primitive Solana réexportée par Core ;
|
||||
- 18 Program IDs fondamentaux possédés par KSP avec paires `PRGID_*` / `PRGIDPK_*` ;
|
||||
- `declare_program_id!` pour construire la représentation texte et `Pubkey` depuis une déclaration canonique unique ;
|
||||
- `ProgramIdEntry`, `ProgramIdFilter`, `ProgramIdKind` et le registre enumerable/recherchable ;
|
||||
- des vues par domaine/famille/protocole et `native_program_ids()` sans registres secondaires ;
|
||||
- une taxonomie extensible séparant notamment `subfamily` et `program_version` ;
|
||||
- les réexports crate-root, rustdocs et tests publics correspondants.
|
||||
|
||||
### Dépendances
|
||||
|
||||
Core ne dépend pas de `ksp-logging-lib`, Config, Wallet, Store, Transport, Program ou Materializer.
|
||||
|
||||
Une primitive Solana/Anza officiellement stable peut être ajoutée seulement lorsqu'un item Core concret en a besoin.
|
||||
|
||||
`solana-pubkey` est un candidat naturel pour les Program IDs ; les autres primitives autorisées ne sont pas ajoutées par anticipation.
|
||||
La seule dépendance externe directe de `ksp-core-lib` à la clôture est `solana-pubkey`, déclarée au workspace avec la génération `^4.3`, `default-features = false`, puis héritée par la crate avec `.workspace = true`. Aucune feature optionnelle supplémentaire n'est activée dans `0.1.1`.
|
||||
|
||||
### Hors scope
|
||||
|
||||
@@ -87,20 +84,20 @@ Une primitive Solana/Anza officiellement stable peut être ajoutée seulement lo
|
||||
|
||||
### Lifecycle de la release
|
||||
|
||||
Le nombre de prereleases n'est pas figé avant `pre.001`.
|
||||
|
||||
Trajectoire candidate :
|
||||
Trajectoire réellement suivie :
|
||||
|
||||
```text
|
||||
pre.001 brainstorming + audit + plan détaillé
|
||||
pre.002 Error/Result + fondation API
|
||||
pre.003 primitives/Program IDs réellement retenus
|
||||
pre.004 compléments/tests/audits
|
||||
pre.005 validation finale/docs/cleanup/prompt 0.1.2
|
||||
pre.001 brainstorming + audit + plan détaillé
|
||||
pre.001-fix.001/.002 corrections de cadrage Program IDs/taxonomie
|
||||
pre.002 Error/Result + fondation API
|
||||
pre.002-fix.001 corrections de tests/lints
|
||||
pre.003 Pubkey + Program IDs
|
||||
pre.003-fix.001 politique Cargo workspace + corrections Clippy
|
||||
pre.004 intégration Core + audits
|
||||
pre.005 validation finale/docs/cleanup/prompt 0.1.2
|
||||
rel.001 publication stable après validation de pre.005
|
||||
```
|
||||
|
||||
Cette séquence est indicative. `pre.001` peut la modifier.
|
||||
|
||||
## `0.1.2` — Logging foundation
|
||||
|
||||
### Dépendances
|
||||
@@ -325,7 +322,7 @@ Les directions restent celles du roadmap :
|
||||
|
||||
Ces séries sont des objectifs fonctionnels, pas un calendrier contractuel.
|
||||
|
||||
# Sélection de la première release
|
||||
# Progression de la série `0.1.x`
|
||||
|
||||
La première release fonctionnelle est :
|
||||
|
||||
@@ -333,10 +330,15 @@ La première release fonctionnelle est :
|
||||
0.1.1 — Core foundation
|
||||
```
|
||||
|
||||
Le prompt de démarrage associé est :
|
||||
Son prompt historique d'ouverture reste :
|
||||
|
||||
```text
|
||||
prompts/001-V0_1_1_START_PROMPT.md
|
||||
```
|
||||
|
||||
`0.0.3` est désormais la base fondatrice stable. La prochaine phase ouvre `0.1.1-pre.001` à partir du prompt final `prompts/001-V0_1_1_START_PROMPT.md`.
|
||||
À la clôture de `0.1.1-pre.005`, la surface Core est prête pour validation puis publication stable via `0.1.1-rel.001`. Après le tag `v0.1.1`, la release suivante s'ouvre avec :
|
||||
|
||||
```text
|
||||
0.1.2 — Logging foundation
|
||||
prompts/002-V0_1_2_START_PROMPT.md
|
||||
```
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
<!-- file: docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Plan KSP 0.1.1 — Core foundation
|
||||
|
||||
## Statut
|
||||
|
||||
Plan de travail de `0.1.1`, établi par `0.1.1-pre.001`.
|
||||
Plan de travail de `0.1.1`, établi par `0.1.1-pre.001` puis consolidé jusqu'à la tranche de clôture `0.1.1-pre.005`.
|
||||
|
||||
Cette première prerelease reste une tranche de brainstorming, audit et planification. Elle ne développe pas encore la surface fonctionnelle Core.
|
||||
La surface fonctionnelle Core prévue par ce plan est désormais implémentée et validée jusqu'à `pre.004`. `pre.005` finalise la documentation, le prompt `0.1.2` et la préparation de publication ; la version stable `0.1.1` reste à publier par un delta `rel.001` après validation de cette dernière prerelease.
|
||||
|
||||
## Base auditée
|
||||
|
||||
@@ -185,6 +185,10 @@ Décision pour `0.1.1` :
|
||||
- n'activer ni Borsh, ni Wincode, ni Serde, ni Rand, ni feature cryptographique par anticipation ;
|
||||
- réexporter le type `Pubkey` depuis `ksp_core_lib` afin que son utilisation fasse partie intentionnellement du contrat Core.
|
||||
|
||||
L'audit final `pre.005` confirme qu'aucune feature optionnelle de `solana-pubkey` ne doit être activée dans `0.1.1`. La surface Core actuelle utilise uniquement l'identité `Pubkey`, la construction compile-time des Program IDs et les opérations déjà disponibles avec la dépendance retenue. Les features `alloc`, `borsh`, `bytemuck`, `curve25519`, `rand`, `serde`, `sha2`, `std` et `wincode` restent need-driven et seront activées uniquement dans la crate propriétaire lorsqu'un contrat réel l'exigera.
|
||||
|
||||
Le `cargo tree -p ksp-core-lib -e features` exécuté par le user montre des features de `solana-address` telles que `copy`, `decode`, `error`, `sanitize`, `syscalls` et `default`. Elles proviennent de la composition interne résolue de `solana-pubkey`/`solana-address` et ne justifient pas d'activer une feature optionnelle KSP supplémentaire sur `solana-pubkey`.
|
||||
|
||||
Depuis `pre.003-fix.001`, la règle générale KSP impose la centralisation des dépendances externes sous `[workspace.dependencies]` et l'héritage `.workspace = true` dans les crates membres. La résolution Cargo observée pour la contrainte `^4.3` reste `solana-pubkey 4.3.0` au moment de cette tranche.
|
||||
|
||||
### `solana-address`
|
||||
@@ -628,23 +632,30 @@ Résultat de l'audit d'intégration :
|
||||
- aucune primitive N1 supplémentaire n'est démontrée nécessaire ;
|
||||
- les modules d'implémentation restent privés et les contrats consommables sont réexportés explicitement au crate-root ;
|
||||
- le test d'intégration public vérifie aussi qu'un consommateur peut déclarer un `const ErrorCode`, usage requis par les futures crates propriétaires de domaines ;
|
||||
- la rustdoc crate-level est complétée pour expliciter la frontière Core ;
|
||||
- les validations de `pre.003-fix.001` communiquées par le user confirment 14 tests unitaires, 3 tests d'intégration, un `cargo tree` limité à `solana-pubkey` et ses dépendances fondamentales, et aucun doublon avec `cargo tree -d`.
|
||||
- la rustdoc crate-level est complétée pour expliciter la frontière Core.
|
||||
|
||||
La tranche ne change ni le contrat Error, ni la taxonomie, ni l'inventaire des 18 Program IDs. Le contrôle résolu des features reste à confirmer sur le dépôt cible avec `cargo tree -p ksp-core-lib -e features` en complément des validations Cargo usuelles.
|
||||
Validations `pre.004` exécutées avec succès par le user le 2026-08-14 :
|
||||
|
||||
- `cargo fmt --all` ;
|
||||
- `cargo check --workspace` ;
|
||||
- `cargo test --workspace` : 14 tests unitaires et 3 tests d'intégration publics réussis ;
|
||||
- `cargo clippy --workspace --all-targets` : succès sans warning communiqué ;
|
||||
- `cargo tree -p ksp-core-lib` : dépendance directe unique `solana-pubkey 4.3.0`, résolvant `solana-address 2.7.0` ;
|
||||
- `cargo tree -p ksp-core-lib -d` : aucun doublon ;
|
||||
- `cargo tree -p ksp-core-lib -e features` : graphe des features inspecté, sans besoin d'activer une feature optionnelle `solana-pubkey` supplémentaire pour le contrat Core actuel.
|
||||
|
||||
La tranche ne change ni le contrat Error, ni la taxonomie, ni l'inventaire des 18 Program IDs.
|
||||
|
||||
### `0.1.1-pre.005` — clôture
|
||||
|
||||
Objectifs :
|
||||
Résultat de clôture préparé :
|
||||
|
||||
- validations finales workspace ;
|
||||
- audits documentaires applicables ;
|
||||
- correction des écarts résiduels ;
|
||||
- documentation finale et éventuel `USAGE.md` de Core si l'API justifie alors un exemple durable ;
|
||||
- nettoyage/archivage des éléments temporaires ;
|
||||
- mise à jour du changelog général s'il existe alors ;
|
||||
- production du prompt final de démarrage `0.1.2` ;
|
||||
- préparation de la publication stable et du tag `v0.1.1`.
|
||||
- aucune nouvelle primitive Core et aucune nouvelle feature `solana-pubkey` ne sont ajoutées ;
|
||||
- les documents de référence de `0.1.1` sont réalignés avec la surface effectivement livrée ;
|
||||
- aucun `README.md`/`USAGE.md` spécifique à la crate n'est ajouté : la rustdoc crate-level et les tests publics couvrent suffisamment la petite surface actuelle ;
|
||||
- aucun changelog général n'existe dans la base actuelle, donc aucun fichier de changelog artificiel n'est créé uniquement pour cette release ;
|
||||
- le prompt final `prompts/002-V0_1_2_START_PROMPT.md` est créé pour ouvrir Logging après publication stable de `0.1.1` ;
|
||||
- la publication stable reste volontairement séparée dans un futur delta `0.1.1-rel.001`, conformément au workflow de versionnement.
|
||||
|
||||
Un `pre.NNN-fix.NNN` corrige la tranche correspondante sans réécrire son historique.
|
||||
|
||||
@@ -669,6 +680,4 @@ Un `pre.NNN-fix.NNN` corrige la tranche correspondante sans réécrire son histo
|
||||
|
||||
## Questions ouvertes non bloquantes
|
||||
|
||||
- Décider en `pre.005`, à partir de l'API réellement stabilisée, si un `README.md`/`USAGE.md` de crate apporte suffisamment de valeur pour être créé maintenant.
|
||||
|
||||
Aucune de ces questions ne justifie d'élargir le périmètre fonctionnel de `0.1.1`.
|
||||
Aucune question ouverte ne bloque la publication de `0.1.1`. Les capacités volontairement différées restent soumises à la règle need-driven des releases futures plutôt qu'à des placeholders Core.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: prompts/000-README.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Prompts KSP
|
||||
|
||||
@@ -21,4 +21,5 @@ Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par
|
||||
|
||||
## Documents
|
||||
|
||||
- [`001-V0_1_1_START_PROMPT.md`](001-V0_1_1_START_PROMPT.md) — prompt final ouvrant la première release fonctionnelle `0.1.1` après publication stable de `0.0.3`.
|
||||
- [`001-V0_1_1_START_PROMPT.md`](001-V0_1_1_START_PROMPT.md) — prompt historique ouvrant la première release fonctionnelle `0.1.1` après publication stable de `0.0.3` ;
|
||||
- [`002-V0_1_2_START_PROMPT.md`](002-V0_1_2_START_PROMPT.md) — prompt final destiné à ouvrir `0.1.2 — Logging foundation` après publication stable de `0.1.1`.
|
||||
|
||||
335
prompts/002-V0_1_2_START_PROMPT.md
Normal file
335
prompts/002-V0_1_2_START_PROMPT.md
Normal file
@@ -0,0 +1,335 @@
|
||||
<!-- file: prompts/002-V0_1_2_START_PROMPT.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Prompt de démarrage KSP 0.1.2
|
||||
|
||||
**Statut : Final — à utiliser après validation et publication stable de `0.1.1`.**
|
||||
|
||||
## 1. Identité
|
||||
|
||||
Release fonctionnelle :
|
||||
|
||||
```text
|
||||
0.1.2 — Logging foundation
|
||||
```
|
||||
|
||||
Deuxième release fonctionnelle de Khadhroony Solana Project.
|
||||
|
||||
## 2. Mission
|
||||
|
||||
Introduire et stabiliser `ksp-logging-lib` comme façade KSP commune et propriétaire du logging/tracing runtime.
|
||||
|
||||
Cette crate doit être la seule crate KSP qui importe directement et configure la stack `tracing` nécessaire à la politique générale de logs. Les autres crates comportementales KSP doivent consommer la façade de `ksp-logging-lib` plutôt que définir chacune leur propre initialisation ou leur propre politique de tracing.
|
||||
|
||||
La release doit établir une surface assez générale pour Logging lui-même et pour les prochaines crates N1, sans ouvrir `ksp-config-lib`, Tauri, Transport, Wallet, Program, Store ou les autres couches supérieures.
|
||||
|
||||
## 3. Base requise
|
||||
|
||||
Base attendue :
|
||||
|
||||
```text
|
||||
0.1.1 stable
|
||||
```
|
||||
|
||||
La session commence uniquement après validation de la dernière prerelease de `0.1.1`, publication du delta final `rel.001` et tag stable :
|
||||
|
||||
```text
|
||||
v0.1.1
|
||||
```
|
||||
|
||||
Dans le workflow KSP, une archive Gitea nommée `khadhroony-solana-project-v0.1.1.zip` provient directement du tag correspondant et constitue une base stable suffisante pour la session.
|
||||
|
||||
## 4. État validé à préserver
|
||||
|
||||
`ksp-core-lib` fournit désormais la fondation N1 commune, notamment :
|
||||
|
||||
```text
|
||||
ksp_core_lib::ErrorCode
|
||||
ksp_core_lib::ErrorContext
|
||||
ksp_core_lib::Error
|
||||
ksp_core_lib::Result<T>
|
||||
ksp_core_lib::Pubkey
|
||||
```
|
||||
|
||||
ainsi que la propriété KSP des Program IDs fondamentaux et leur registre descriptif.
|
||||
|
||||
Logging peut dépendre de `ksp-core-lib` pour `Error` / `Result`. La relation inverse reste interdite : Core ne dépend pas de Logging.
|
||||
|
||||
La politique Cargo établie dans `0.1.1` doit être conservée :
|
||||
|
||||
- toute dépendance externe est déclarée au `Cargo.toml` racine sous `[workspace.dependencies]` ;
|
||||
- une crate membre consomme ces dépendances avec `<crate>.workspace = true` ;
|
||||
- les versions sont exprimées avec une génération compatible explicite telle que `^M.m`, sauf pin justifié ;
|
||||
- les features et `default-features` sont activées uniquement lorsqu'un besoin concret le démontre.
|
||||
|
||||
## 5. Sources de vérité internes
|
||||
|
||||
Relire en priorité les fichiers réellement présents dans la base, notamment :
|
||||
|
||||
- `ROADMAP.md` ;
|
||||
- `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` ;
|
||||
- `docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.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/rules/RULES_RUST.md` ;
|
||||
- `docs/rules/VERSION_WORKFLOW.md` ;
|
||||
- `docs/IDEAS.md` ;
|
||||
- les deltas `deltas/0.1.1/*`.
|
||||
|
||||
Relire aussi les règles/index racine supplémentaires présents au moment de la session. Ne jamais inventer un document absent de la base.
|
||||
|
||||
## 6. Sources externes normatives
|
||||
|
||||
Avant d'ajouter `tracing`, `tracing-subscriber`, `tracing-appender` ou toute crate liée :
|
||||
|
||||
- vérifier les versions publiées actuelles depuis les sources officielles Tokio/tracing et crates.io/docs.rs ;
|
||||
- examiner leurs features et dépendances réelles ;
|
||||
- identifier le MSRV/toolchain pertinent ;
|
||||
- éviter d'activer les default features ou features optionnelles uniquement par commodité ;
|
||||
- examiner `cargo tree` et `cargo tree -e features` après intégration.
|
||||
|
||||
La première prerelease doit choisir les dépendances réellement nécessaires à l'API retenue ; la présence architecturale d'une crate candidate n'oblige pas à l'ajouter si la surface finale n'en a pas besoin.
|
||||
|
||||
## 7. Première prerelease obligatoire : `0.1.2-pre.001`
|
||||
|
||||
`pre.001` est d'abord une prerelease de **brainstorming, audit et planification**.
|
||||
|
||||
Elle doit au minimum :
|
||||
|
||||
1. inventorier l'état réel du workspace et confirmer la création/absence actuelle de `ksp-logging-lib` ;
|
||||
2. auditer la stack `tracing` officielle actuelle, ses versions, features et dépendances ;
|
||||
3. définir précisément la frontière entre façade KSP, initialisation et backend/subscriber ;
|
||||
4. déterminer si l'API publique principale doit utiliser des macros, des fonctions ou une combinaison ;
|
||||
5. préserver les callsites/source locations réels pour les événements de logging ;
|
||||
6. définir les niveaux KSP `error`, `warn`, `info`, `debug`, `trace` ;
|
||||
7. définir les champs structurés communs utiles maintenant, notamment `target`, `domain`, `component` ou équivalents sans inventer une taxonomie trop rigide ;
|
||||
8. définir le contrat de settings runtime de Logging sans dépendre de Config ;
|
||||
9. définir le lifecycle d'initialisation, les erreurs d'initialisation et le comportement d'une initialisation répétée ;
|
||||
10. étudier console, fichiers, filtering, appender non bloquant et rotation uniquement selon les besoins de la première surface ;
|
||||
11. traiter explicitement la durée de vie/ownership des guards nécessaires aux writers non bloquants si cette voie est retenue ;
|
||||
12. définir la stratégie de prévention des secrets dans les logs ;
|
||||
13. proposer l'API publique et les crate-root reexports ;
|
||||
14. proposer les tests unitaires/intégration et audits de dépendances ;
|
||||
15. dimensionner les prereleases suivantes ;
|
||||
16. confirmer les hors-scope.
|
||||
|
||||
Ne pas transformer `pre.001` en une grosse phase de développement avant validation du plan.
|
||||
|
||||
## 8. Responsabilité de `ksp-logging-lib`
|
||||
|
||||
La direction acquise est :
|
||||
|
||||
```text
|
||||
ksp-logging-lib
|
||||
-> ksp-core-lib
|
||||
-> tracing stack réellement retenue
|
||||
```
|
||||
|
||||
`ksp-logging-lib` doit être la façade commune de logging/tracing du projet et le propriétaire de la politique runtime correspondante.
|
||||
|
||||
Les crates comportementales KSP pourront dépendre directement de `ksp-logging-lib` et utiliser sa surface KSP pour :
|
||||
|
||||
```text
|
||||
error
|
||||
warn
|
||||
info
|
||||
debug
|
||||
trace
|
||||
```
|
||||
|
||||
avec les champs structurés réellement retenus par `pre.001`.
|
||||
|
||||
Les crates `*-api` purement déclaratives restent sans dépendance logging par défaut lorsqu'elles n'ont aucun comportement réel à tracer.
|
||||
|
||||
## 9. Callsite et macros
|
||||
|
||||
L'audit doit porter une attention particulière à la préservation du callsite réel.
|
||||
|
||||
Une simple fonction wrapper autour d'une macro `tracing::*` peut enregistrer le fichier/module/ligne du wrapper plutôt que ceux de l'appelant. La surface KSP doit donc être conçue pour préserver correctement les métadonnées de callsite, quitte à exposer des macros KSP qui délèguent aux macros `tracing` au point d'appel.
|
||||
|
||||
Le design exact des macros/fonctions et leurs noms sont décidés dans `pre.001`, puis testés avant stabilisation.
|
||||
|
||||
## 10. Settings et Config
|
||||
|
||||
`ksp-logging-lib` ne dépend pas de `ksp-config-lib`.
|
||||
|
||||
Logging possède les settings runtime strictement nécessaires à son initialisation. `ksp-config-lib`, lorsqu'il sera développé en `0.1.3`, pourra lire/résoudre ses documents puis convertir explicitement la configuration obtenue vers les settings publics de Logging.
|
||||
|
||||
Ne pas introduire de document JSON/TOML de configuration global dans Logging uniquement pour anticiper Config.
|
||||
|
||||
## 11. Sorties et lifecycle
|
||||
|
||||
Le `pre.001` doit déterminer la première surface réellement utile parmi :
|
||||
|
||||
- console/stdout/stderr ;
|
||||
- fichiers ;
|
||||
- filtrage global et/ou par target/domain ;
|
||||
- format lisible et/ou structuré ;
|
||||
- rotation ;
|
||||
- writer non bloquant ;
|
||||
- flush/shutdown propre.
|
||||
|
||||
Lorsque `tracing-appender::non_blocking` ou un mécanisme équivalent est retenu, la durée de vie du guard doit être possédée par un objet/lifecycle KSP explicite afin d'éviter une perte silencieuse de logs à la fin du scope d'initialisation.
|
||||
|
||||
Une capacité non nécessaire à la première validation n'est pas ajoutée par anticipation.
|
||||
|
||||
## 12. Erreurs
|
||||
|
||||
Les erreurs Logging utilisent le contrat Core :
|
||||
|
||||
```text
|
||||
ksp_core_lib::Error
|
||||
ksp_core_lib::Result<T>
|
||||
```
|
||||
|
||||
`ksp-logging-lib` définit ses propres constantes `ErrorCode` dans son domaine sans ajouter de variante ou de connaissance Logging à `ksp-core-lib`.
|
||||
|
||||
Les causes externes utiles sont conservées via le contrat `source` Core lorsqu'elles satisfont les bornes prévues.
|
||||
|
||||
Aucun `unwrap`, `expect`, `panic` production ou opérateur `?` n'est utilisé.
|
||||
|
||||
## 13. Secrets et données sensibles
|
||||
|
||||
Logging ne doit pas devenir un canal de fuite de secrets.
|
||||
|
||||
`pre.001` doit au minimum définir :
|
||||
|
||||
- quels champs sont interdits par politique ;
|
||||
- comment les settings sensibles sont exclus ;
|
||||
- quelles données doivent être explicitement redacted/omises par les appelants ;
|
||||
- si des helpers de redaction génériques sont réellement nécessaires maintenant.
|
||||
|
||||
Ne pas logger automatiquement les contenus de clés privées, seeds, passwords, tokens d'API ou autres secrets.
|
||||
|
||||
## 14. Dépendances et propriété
|
||||
|
||||
Interdictions :
|
||||
|
||||
```text
|
||||
ksp-core-lib -X-> ksp-logging-lib
|
||||
ksp-logging-lib -X-> ksp-config-lib
|
||||
ksp-logging-lib -X-> wallet/transport/program/store/workers/jobs/apps
|
||||
```
|
||||
|
||||
`ksp-logging-lib` est la seule crate KSP qui doit normalement importer directement `tracing` et réaliser la configuration du subscriber/appender retenu.
|
||||
|
||||
Une application Tauri future peut exceptionnellement devoir intégrer une crate/plugin tracing imposée par son framework. Cette exception reste au niveau adaptateur/application et ne crée pas une seconde politique de logging parallèle à `ksp-logging-lib`.
|
||||
|
||||
## 15. Hors scope strict de `0.1.2`
|
||||
|
||||
- `ksp-config-lib` et documents/profils Config ;
|
||||
- application Tauri ;
|
||||
- wallet/keypair/signer ;
|
||||
- RPC/WS/providers ;
|
||||
- Program decoding/execution ;
|
||||
- Store/PostgreSQL ;
|
||||
- materializers ;
|
||||
- workers/jobs/pipelines ;
|
||||
- scenarios ;
|
||||
- trading/ML ;
|
||||
- OpenTelemetry ou export réseau de traces, sauf besoin concret explicitement revalidé et borné ;
|
||||
- observability distribuée complète.
|
||||
|
||||
## 16. Règles Rust et Cargo
|
||||
|
||||
Préserver les règles workspace, notamment :
|
||||
|
||||
- Rust 2024 ;
|
||||
- async-first pour les I/O futures lorsque pertinent, sans rendre artificiellement async les appels de logging synchrones ;
|
||||
- `unsafe` interdit ;
|
||||
- `unwrap` / `expect` interdits ;
|
||||
- `panic` interdit en production ;
|
||||
- opérateur `?` interdit ;
|
||||
- returns explicites, y compris dans les closures lorsque Clippy l'exige ;
|
||||
- `unreachable_pub = deny` ;
|
||||
- `missing_docs = warn` ;
|
||||
- imports de traits seulement lorsque nécessaire ;
|
||||
- réexports crate-root explicites ;
|
||||
- pas de `mod.rs` ;
|
||||
- pas de `pub(super)` / `pub(in ...)` ;
|
||||
- code/Rustdoc en anglais ;
|
||||
- tests unitaires externes au `src` selon la convention du dépôt ;
|
||||
- dépendances externes centralisées sous `[workspace.dependencies]`.
|
||||
|
||||
## 17. Git et deltas
|
||||
|
||||
À partir de `0.1.x`, chaque delta est commité :
|
||||
|
||||
```text
|
||||
pre.NNN
|
||||
pre.NNN-fix.NNN
|
||||
rel.NNN
|
||||
```
|
||||
|
||||
Une erreur est corrigée par le delta suivant ; l'historique n'est pas réécrit.
|
||||
|
||||
Seul le commit final validé comme stable reçoit :
|
||||
|
||||
```text
|
||||
v0.1.2
|
||||
```
|
||||
|
||||
## 18. 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 crate/settings + façade levels/callsites
|
||||
pre.003 initialisation + console/filtering
|
||||
pre.004 fichiers/appender/rotation/lifecycle si retenus
|
||||
pre.005 intégration/tests/audits
|
||||
pre.006 validation finale/docs/cleanup/prompt 0.1.3
|
||||
```
|
||||
|
||||
Scinder une tranche si son périmètre devient trop large. Supprimer/réorganiser une tranche si le `pre.001` démontre qu'une capacité candidate n'est pas nécessaire.
|
||||
|
||||
## 19. Validations attendues
|
||||
|
||||
Lorsque les commandes sont applicables :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo tree -p ksp-logging-lib
|
||||
cargo tree -p ksp-logging-lib -d
|
||||
cargo tree -p ksp-logging-lib -e features
|
||||
```
|
||||
|
||||
Exécuter également les scripts/audits réellement présents dans le dépôt.
|
||||
|
||||
Aucune validation non exécutée ne doit être déclarée réussie.
|
||||
|
||||
## 20. Critères de sortie
|
||||
|
||||
`0.1.2` peut être publiée stable lorsque :
|
||||
|
||||
- la façade Logging et son ownership sont clairs ;
|
||||
- les callsites sont préservés par tests ;
|
||||
- les cinq niveaux KSP nécessaires sont utilisables ;
|
||||
- l'initialisation choisie est déterministe et testée ;
|
||||
- console/fichiers/filtering/lifecycle retenus sont validés ;
|
||||
- les erreurs utilisent Core sans dépendance inverse ;
|
||||
- aucune dépendance Config ou domaine supérieur n'a été introduite ;
|
||||
- les secrets sont protégés par une politique documentée/testable ;
|
||||
- le graphe de dépendances/features est audité ;
|
||||
- les validations workspace sont propres ;
|
||||
- la documentation finale et le prompt de la release suivante sont prêts.
|
||||
|
||||
## 21. Release suivante
|
||||
|
||||
La release suivante prévue est :
|
||||
|
||||
```text
|
||||
0.1.3 — ksp-config-lib
|
||||
```
|
||||
|
||||
Son périmètre concret reste soumis au `pre.001` correspondant et peut être scindé si Config s'avère trop large pour une seule release.
|
||||
Reference in New Issue
Block a user