v0.1.1-pre.002

deltas/0.1.1/pre.002.md

@@ -0,0 +1,215 @@
+<!-- file: deltas/0.1.1/pre.002.md -->
+<!-- version: 1 -->
+
+# Delta 0.1.1-pre.002
+
+## Base requise
+
+Commit de livraison attendu :
+
+```text
+v0.1.1-pre.001-fix.002
+```
+
+Le plan actif est `docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md` version documentaire 4, incluant le réalignement du tableau des cas représentatifs effectué avant le commit du correctif précédent.
+
+## Objectif
+
+Implémenter la première surface fonctionnelle de `ksp-core-lib` : le contrat commun ouvert `Error` / `Result` validé pendant `pre.001`.
+
+Cette tranche reste strictement bornée à l'erreur commune et n'ouvre aucune dépendance Solana ni aucun Program ID.
+
+## Version Cargo
+
+`workspace.package.version` passe de :
+
+```text
+0.1.1-pre.1
+```
+
+à :
+
+```text
+0.1.1-pre.2
+```
+
+L'identifiant Cargo respecte SemVer sans zéro initial ; l'identifiant de livraison reste `0.1.1-pre.002`.
+
+Le header de `Cargo.toml` passe de version 18 à 19.
+
+## Fichiers ajoutés
+
+- `crates/ksp-core-lib/src/error.rs`
+- `crates/ksp-core-lib/unit_tests/error.rs`
+- `crates/ksp-core-lib/tests/public_api.rs`
+- `deltas/0.1.1/pre.002.md`
+
+## Fichiers modifiés
+
+- `Cargo.toml`
+- `crates/ksp-core-lib/src/lib.rs`
+- `docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`
+
+## Fichiers supprimés
+
+Aucun.
+
+## Contrat implémenté
+
+### `ErrorCode`
+
+`ErrorCode` contient uniquement :
+
+```text
+domain: &'static str
+code: &'static str
+```
+
+Décisions :
+
+- `ErrorCode::new(...)` est `const` afin que chaque crate supérieure puisse définir ses propres codes statiques ;
+- Core ne possède aucune enum centrale des domaines ;
+- `domain()` et `code()` exposent les deux identifiants stables ;
+- `ErrorCode` est `Copy`, `Clone`, `Eq`, `PartialEq`, `Hash` et `Debug` parce qu'il ne contient que deux chaînes statiques.
+
+### `ErrorContext`
+
+`ErrorContext` contient :
+
+```text
+key: &'static str
+value: String
+```
+
+Le contexte conserve son ordre d'insertion dans `Error`.
+
+L'API publique expose `ErrorContext::new(...)`, `key()` et `value()`.
+
+### `Error`
+
+`Error` contient :
+
+```text
+code: ErrorCode
+message: String
+context: Vec<ErrorContext>
+source: Option<Box<dyn std::error::Error + Send + Sync + 'static>>
+```
+
+Décisions stabilisées :
+
+- `Error::new(...)` construit l'erreur minimale ;
+- `with_context(...)` consomme `self`, ajoute un champ puis retourne l'erreur enrichie ;
+- `with_source(...)` suit le même modèle pour une cause externe ;
+- aucune méthode mutable publique parallèle n'est ajoutée ;
+- aucune conversion générique `From<ExternalError>` n'est introduite ;
+- `Error` ne dérive pas `Clone`, `Eq` ou `PartialEq`, afin de ne pas affaiblir le support d'une vraie cause externe ;
+- `Error` implémente `std::fmt::Display` et `std::error::Error` ;
+- le rendu `Display` est exactement :
+
+```text
+<domain>.<code>: <message>
+```
+
+Le contexte et la chaîne de causes ne sont pas injectés automatiquement dans ce rendu.
+
+### `Result<T>`
+
+La façade expose :
+
+```text
+ksp_core_lib::Result<T> = std::result::Result<T, ksp_core_lib::Error>
+```
+
+## Façade Core
+
+`crates/ksp-core-lib/src/lib.rs` ouvre le module d'implémentation en privé puis réexporte explicitement :
+
+```text
+ksp_core_lib::Error
+ksp_core_lib::ErrorCode
+ksp_core_lib::ErrorContext
+ksp_core_lib::Result
+```
+
+Aucun `pub mod` n'est introduit.
+
+## Dépendances
+
+Aucune dépendance n'est ajoutée à `ksp-core-lib` pendant cette tranche.
+
+En particulier, `pre.002` n'introduit ni `thiserror`, ni `anyhow`, ni crate Solana, ni codec wire.
+
+## Tests ajoutés
+
+### Tests unitaires externes
+
+`crates/ksp-core-lib/unit_tests/error.rs` vérifie :
+
+- conservation de `domain` et `code` ;
+- possibilité de déclarer un `ErrorCode` constant ;
+- conservation des champs `ErrorContext` ;
+- conservation du message et de l'ordre du contexte ;
+- rendu exact de `Display` ;
+- absence du contexte et de la cause dans le rendu ;
+- conservation de la cause via `std::error::Error::source()` ;
+- propriété `Send + Sync` de l'erreur commune.
+
+Le fichier est rattaché au module privé de production via `#[cfg(test)]` et `#[path = "../unit_tests/error.rs"]`.
+
+### Test d'intégration
+
+`crates/ksp-core-lib/tests/public_api.rs` consomme exclusivement la façade crate-root et vérifie que `Error`, `ErrorCode`, `ErrorContext` et `Result` sont utilisables depuis une crate externe.
+
+## Documentation de plan
+
+Le plan passe de version documentaire 4 à 5 afin de remplacer les deux questions désormais résolues par les décisions réellement implémentées :
+
+- `with_context(...)` consomme `self` ;
+- `Display` utilise la forme stable `<domain>.<code>: <message>`.
+
+Les questions `pre.003` concernant `solana-pubkey` restent ouvertes et inchangées.
+
+## Validations exécutées
+
+Dans l'environnement de préparation :
+
+- reconstruction de la base `0.1.1-pre.001-fix.002` depuis la release `0.0.3` et les deltas successifs ;
+- prise en compte de la version 4 du plan fournie après réalignement manuel du tableau ;
+- contrôle du périmètre des fichiers modifiés/ajoutés ;
+- parsing TOML statique du manifest racine ;
+- contrôle des headers `file:` / `version:` et des fins de ligne des fichiers livrés ;
+- recherche statique des usages interdits `unsafe`, `unwrap`, `expect`, `panic` et opérateur `?` dans le code de production ajouté ;
+- contrôle de l'absence de `use` dans le code Rust ajouté ;
+- contrôle de l'absence de nouvelle dépendance Cargo.
+
+## Validations non exécutées
+
+L'environnement de préparation ne contient ni `cargo` ni `rustc`.
+
+Les commandes suivantes n'ont donc pas pu être exécutées ici :
+
+```bash
+cargo fmt --all
+cargo check --workspace
+cargo test --workspace
+cargo clippy --workspace --all-targets
+```
+
+Elles doivent être exécutées sur le dépôt réel avant validation du commit. Aucun succès Cargo n'est déclaré par ce delta.
+
+## Décisions prises
+
+- Le contrat Error/Result ouvert de `pre.001` est retenu sans enum centrale de domaines.
+- `ErrorCode::new(...)` est `const`.
+- Les champs des types publics restent privés et sont accessibles par API explicite.
+- Le contexte est ordonné et enrichi par consommation de `self`.
+- La cause standard est conservée avec les bornes `Error + Send + Sync + 'static`.
+- `Display` est volontairement court et stable ; Logging décidera plus tard comment exploiter contexte et causes.
+- Core ne possède aucune conversion vers les erreurs des domaines supérieurs.
+
+## Questions ouvertes
+
+Aucune question bloquante pour `pre.002`.
+
+Les questions relatives à `Pubkey`, aux Program IDs et à leur registre restent réservées à `0.1.1-pre.003` conformément au plan actif.