Sasedev/khadhroony-solana-project

Fork 0

Files

SinuS Von SifriduS 11ca53ba48 v0.1.1-pre.005

2026-08-14 16:04:45 +02:00

13 KiB

Raw Blame History

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 :

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 :

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 :

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 :

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 :

inventorier l'état réel du workspace et confirmer la création/absence actuelle de ksp-logging-lib ;
auditer la stack tracing officielle actuelle, ses versions, features et dépendances ;
définir précisément la frontière entre façade KSP, initialisation et backend/subscriber ;
déterminer si l'API publique principale doit utiliser des macros, des fonctions ou une combinaison ;
préserver les callsites/source locations réels pour les événements de logging ;
définir les niveaux KSP error, warn, info, debug, trace ;
définir les champs structurés communs utiles maintenant, notamment target, domain, component ou équivalents sans inventer une taxonomie trop rigide ;
définir le contrat de settings runtime de Logging sans dépendre de Config ;
définir le lifecycle d'initialisation, les erreurs d'initialisation et le comportement d'une initialisation répétée ;
étudier console, fichiers, filtering, appender non bloquant et rotation uniquement selon les besoins de la première surface ;
traiter explicitement la durée de vie/ownership des guards nécessaires aux writers non bloquants si cette voie est retenue ;
définir la stratégie de prévention des secrets dans les logs ;
proposer l'API publique et les crate-root reexports ;
proposer les tests unitaires/intégration et audits de dépendances ;
dimensionner les prereleases suivantes ;
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 :

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 :

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 :

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 :

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

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 :

v0.1.2

18. Dimensionnement indicatif

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

Trajectoire candidate uniquement :

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 :

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 :

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.

13 KiB Raw Blame History