0.1.0

migration/khadhroony-bot2-reference/kb_execution_safety/README.md

@@ -0,0 +1,55 @@
+<!-- file: kb_execution_safety/README.md -->
+<!-- version: 3 -->
+
+# kb_execution_safety
+
+Cette crate applique des contrôles stateless communs aux plans préparés avant simulation, puis avant signature et envoi. Elle ne construit pas de transaction et n’effectue aucun I/O.
+
+## API publique
+
+| Export                      | Usage                                                      |
+|-----------------------------|------------------------------------------------------------|
+| `ExecutionSafetyChecker`    | Point d’entrée stateless des évaluations de sécurité.      |
+| `ExecutionSafetyDecision`   | Décision agrégée `Deny`, `RequireConfirmation` ou `Allow`. |
+| `ExecutionSafetyEvaluation` | Décision accompagnée de toutes les violations stables.     |
+| `ExecutionSafetyViolation`  | Code machine-readable et message humain d’un refus.        |
+
+### `ExecutionSafetyChecker::evaluate_plan(plan)`
+
+Évalue l’ancien `ExecutionPlan`. Ce contrat historique ne contient pas assez d’informations pour autoriser directement une exécution ; la décision reste donc conservatrice et exige une confirmation.
+
+### `ExecutionSafetyChecker::evaluate_prepared_plan(plan)`
+
+Décide si un `PreparedExecutionPlan` peut atteindre la simulation RPC. La fonction vérifie notamment :
+
+- présence d’instructions et de signataires ;
+- simulation obligatoire ;
+- recent blockhash borné ou durable nonce complet ;
+- cohérence entre signataires d’instruction, signataires déclarés et liste autorisée ;
+- plafond de frais présent ;
+- dépense et prix de compute unit sous leurs plafonds ;
+- Mainnet explicitement autorisé et confirmé.
+
+### `ExecutionSafetyChecker::evaluate_send(plan, simulation)`
+
+Réévalue le plan puis décide si la simulation exacte permet la signature et l’envoi. La fonction refuse :
+
+- dry-run encore actif ;
+- simulation absente ou échouée ;
+- blockhash remplacé pendant la simulation ;
+- cluster, blockhash ou nonce observé différent du plan ;
+- frais simulés supérieurs au plafond ;
+- confirmation Mainnet manquante.
+
+## Exemple
+
+```rust
+let checker = kb_execution_safety::ExecutionSafetyChecker;
+let before_simulation = checker.evaluate_prepared_plan(&plan)?;
+if before_simulation.decision != kb_execution_safety::ExecutionSafetyDecision::Allow {
+    // Surface the stable violations and stop.
+}
+let before_send = checker.evaluate_send(&plan, &simulation)?;
+```
+
+Une décision `Allow` ne remplace pas la validation cryptographique du message ou des signatures. Cette responsabilité appartient à `kb_execution_solana`.