From 11ca53ba488ef77871c32088c695e00830237ac4 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Fri, 14 Aug 2026 16:04:45 +0200 Subject: [PATCH] v0.1.1-pre.005 --- Cargo.toml | 4 +- deltas/0.1.1/pre.005.md | 191 ++++++++++ docs/000-README.md | 7 +- docs/plans/000-README.md | 6 +- docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md | 58 +-- docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md | 45 ++- prompts/000-README.md | 5 +- prompts/002-V0_1_2_START_PROMPT.md | 335 ++++++++++++++++++ 8 files changed, 595 insertions(+), 56 deletions(-) create mode 100644 deltas/0.1.1/pre.005.md create mode 100644 prompts/002-V0_1_2_START_PROMPT.md diff --git a/Cargo.toml b/Cargo.toml index 0c5edc6..ba5db51 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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" diff --git a/deltas/0.1.1/pre.005.md b/deltas/0.1.1/pre.005.md new file mode 100644 index 0000000..ee407fc --- /dev/null +++ b/deltas/0.1.1/pre.005.md @@ -0,0 +1,191 @@ + + + +# 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 +``` diff --git a/docs/000-README.md b/docs/000-README.md index 185b8c1..2baebc4 100644 --- a/docs/000-README.md +++ b/docs/000-README.md @@ -1,5 +1,5 @@ - + # 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. diff --git a/docs/plans/000-README.md b/docs/plans/000-README.md index 36c562b..4fef47b 100644 --- a/docs/plans/000-README.md +++ b/docs/plans/000-README.md @@ -1,5 +1,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. diff --git a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md index 85b1792..8f5768c 100644 --- a/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md +++ b/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md @@ -1,5 +1,5 @@ - + # 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` 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` 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 +``` diff --git a/docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md b/docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md index 74f66a3..cd00ce6 100644 --- a/docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md +++ b/docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md @@ -1,13 +1,13 @@ - + # 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. diff --git a/prompts/000-README.md b/prompts/000-README.md index 9223c1f..810ad6a 100644 --- a/prompts/000-README.md +++ b/prompts/000-README.md @@ -1,5 +1,5 @@ - + # 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`. diff --git a/prompts/002-V0_1_2_START_PROMPT.md b/prompts/002-V0_1_2_START_PROMPT.md new file mode 100644 index 0000000..87d7f7c --- /dev/null +++ b/prompts/002-V0_1_2_START_PROMPT.md @@ -0,0 +1,335 @@ + + + +# 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 +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 `.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 +``` + +`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.