v0.4.8-pre.007

kb-lib/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: kb-lib/USAGE.md -->
-<!-- version: 12 -->
+<!-- version: 13 -->
 
 # Utilisation de kb-lib
 
@@ -226,7 +226,8 @@ Les signatures exactes doivent être vérifiées lors de l’utilisation : certa
 - `ExSplTokenExecutor` ;
 - `ExSplAssociatedTokenAccountExecutor` ;
 - `ExSplToken2022Executor` ;
-- `ExSplElgamalRegistryExecutor`.
+- `ExSplElgamalRegistryExecutor` ;
+- `ExMetadataSolanaProgramMetadataExecutor`.
 
 ```rust
 use kb_lib::{ExApiTypedInstructionExecutor, ExSplMemoExecutor};
@@ -235,7 +236,6 @@ let executor = ExSplMemoExecutor;
 let plan = ExApiTypedInstructionExecutor::build_prepared_plan(
     &executor,
     &intent,
-    &policy,
 );
 ```
 
@@ -256,6 +256,41 @@ println!("required_signers={}", plan.required_signers.len());
 
 Memo v1 et v3 restent non exécutables. Memo v4 est la seule génération exécutable.
 
+
+## Exécution Solana Program Metadata
+
+`ExMetadataSolanaProgramMetadataExecutor` couvre les neuf opérations stables `Write`, `Initialize`, `SetAuthority`, `SetData`, `SetImmutable`, `Trim`, `Close`, `Allocate` et `Extend`. Les helpers publics dérivent les PDA canonical et non-canonical ; l’appelant doit toujours fournir et vérifier le compte attendu avant construction du plan.
+
+Les mutations écrasantes, destructrices ou irréversibles ne sont pas retirées de l’API. Elles exigent `allow_destructive_operation = true`, puis le plan complet est évalué par `ExSafetyChecker`. Cette approbation locale ne remplace ni la simulation RPC, ni la confirmation opérateur, ni les postconditions stateful.
+
+```rust
+let intent = kb_lib::ExMetadataSpmExecutionIntent {
+    intent_id: "extend-program-metadata".to_string(),
+    fee_payer: authority.clone(),
+    policy,
+    allow_destructive_operation: false,
+    operation: kb_lib::ExMetadataSpmOperation::Extend {
+        account: metadata_account,
+        authority,
+        length: 256,
+        program_context: std::option::Option::None,
+    },
+};
+let executor = kb_lib::ExMetadataSolanaProgramMetadataExecutor;
+let plan = match kb_lib::ExApiTypedInstructionExecutor::build_prepared_plan(
+    &executor,
+    &intent,
+) {
+    std::result::Result::Ok(value) => value,
+    std::result::Result::Err(error) => return std::result::Result::Err(error),
+};
+```
+
+`Initialize` et `Allocate` n’inventent pas le financement préalable nécessaire à l’exemption de rent. La préparation de fixture ou l’orchestration stateful doit calculer le financement depuis le RPC, préfinancer le PDA ou le compte keypair, puis simuler le message exact avant soumission.
+
+Les contenus inline sont volontairement bornés à 1 024 octets par le workspace. Les contenus plus grands passent par un compte `Buffer` préfinancé, écrit par segments puis consommé par `Initialize` ou `SetData`.
+Pour `Initialize` et les allocations de Buffer PDA, le booléen `canonical` est fourni explicitement. La présence de `program_data` ne suffit pas à déterminer la dérivation, car les programmes issus de loaders antérieurs peuvent être canoniques sans compte ProgramData.
+
 ## Exécution Metaplex Token Metadata
 
 La surface publique repose sur :