v0.2.13-pre.007

crates/ksp-interface-lib/USAGE.md

@@ -1,24 +1,122 @@
 <!-- file: crates/ksp-interface-lib/USAGE.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Usage de ksp-interface-lib
 
-Cette page décrit la surface publique actuellement matérialisée par la foundation Interface. Les APIs d'instruction sont ajoutées progressivement sans exposer les modules internes.
+Cette page décrit la façade publique matérialisée par `0.2.13`. Les modules internes ne font pas partie du contrat consommable : utiliser uniquement les exports du crate-root.
 
-## Utiliser le Pubkey canonique
-
-Interface réexporte le `Pubkey` possédé par Core afin que les futurs contrats wire puissent partager la même primitive sans wrapper parallèle :
+## Construire des account metas
 
 ```rust
-let program_id = ksp_interface_lib::Pubkey::default();
-let bytes = program_id.to_bytes();
-assert_eq!(bytes.len(), 32);
+let readonly_account = ksp_interface_lib::Pubkey::new_from_array([1_u8; 32]);
+let writable_account = ksp_interface_lib::Pubkey::new_from_array([2_u8; 32]);
+
+let readonly = ksp_interface_lib::ProgramAccountMeta::readonly(readonly_account, true);
+let writable = ksp_interface_lib::ProgramAccountMeta::writable(writable_account, false);
+
+assert_eq!(readonly.pubkey(), &readonly_account);
+assert!(readonly.is_signer());
+assert!(!readonly.is_writable());
+
+assert_eq!(writable.pubkey(), &writable_account);
+assert!(!writable.is_signer());
+assert!(writable.is_writable());
 ```
 
-Un consumer ne doit pas reconstruire une identité Program textuelle propre à Interface. Les Program IDs fondamentaux restent possédés et répertoriés par `ksp-core-lib`.
+`readonly`/`writable` décrivent uniquement les flags wire de l'account meta. Interface ne valide pas l'identité du compte contre un registry Program.
 
-## Surface volontairement absente
+## Construire une instruction passive
 
-La foundation initiale n'expose encore aucun constructeur d'instruction fonctionnel. Elle ne fournit pas non plus de codec générique Borsh/Wincode, de sérialisation Serde, de transport ou de comportement Program. Ces surfaces sont ajoutées uniquement lorsque leur contrat réel est matérialisé et borné.
+```rust
+let program_id = ksp_interface_lib::Pubkey::new_from_array([3_u8; 32]);
+let account_id = ksp_interface_lib::Pubkey::new_from_array([4_u8; 32]);
 
-Aucun runtime logging n'est nécessaire pour les contrats passifs actuels ; une future instrumentation comportementale devrait passer par `ksp-logging-lib` selon les règles KSP au lieu d'introduire `tracing` directement.
+let account = ksp_interface_lib::ProgramAccountMeta::writable(account_id, true);
+let result = ksp_interface_lib::ProgramInstruction::try_new(
+    program_id,
+    std::vec![account, account],
+    std::vec![7_u8, 8, 9],
+);
+
+match result {
+    std::result::Result::Ok(instruction) => {
+        assert_eq!(instruction.program_id(), &program_id);
+        assert_eq!(instruction.accounts(), &[account, account]);
+        assert_eq!(instruction.data(), &[7_u8, 8, 9]);
+    }
+    std::result::Result::Err(error) => {
+        eprintln!("{error}");
+    }
+}
+```
+
+L'ordre et les doublons des accounts sont conservés. Les octets `data` restent opaques : `ProgramInstruction` ne les sérialise, désérialise ni interprète.
+
+Les `Vec` fournis à `try_new` sont consommés par la structure après validation des bornes ; aucun clone ou reformatage interne n'est requis par le contrat actuel.
+
+## Bornes
+
+Les limites publiques sont :
+
+```rust
+assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_ACCOUNTS, 255);
+assert_eq!(ksp_interface_lib::MAX_PROGRAM_INSTRUCTION_DATA_LEN, 10_240);
+```
+
+`255` account metas et `10_240` bytes de data sont admis. `256` account metas ou `10_241` bytes sont refusés par `try_new` avant création d'un `ProgramInstruction` valide.
+
+Ces limites sont des bornes locales Interface et ne promettent pas qu'une instruction admise respecte à elle seule toutes les contraintes de taille/account-set d'une transaction Solana complète.
+
+## Observer une erreur de limite
+
+Le code public est :
+
+```rust
+assert_eq!(
+    ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED.domain(),
+    "interface",
+);
+assert_eq!(
+    ksp_interface_lib::ERROR_CODE_PROGRAM_INSTRUCTION_LIMIT_EXCEEDED.code(),
+    "program_instruction_limit_exceeded",
+);
+```
+
+Une erreur de dépassement expose uniquement un contexte structurel sûr :
+
+```text
+field
+actual_len
+maximum_len
+```
+
+Le contenu du payload et les account metas arbitraires ne sont pas projetés dans le diagnostic.
+
+## Debug borné
+
+Le `Debug` de `ProgramInstruction` contient uniquement :
+
+```text
+program_id
+account_count
+data_len
+```
+
+Il ne faut donc pas attendre de ce rendu une sérialisation wire ou un dump du payload.
+
+## Dépendances à ne pas ajouter côté consumer
+
+Un consumer de la façade Interface n'a pas besoin d'ajouter un SDK Program Solana uniquement pour reconstruire `ProgramInstruction`. La crate utilise le `Pubkey` canonique partagé avec Core et conserve son propre contrat passif.
+
+La foundation ne fournit volontairement pas :
+
+```text
+serde générique
+Borsh / Wincode générique
+solana-instruction interop automatique
+transport réseau
+Program decoder/preparer
+signing/execution
+```
+
+Ces surfaces doivent être introduites dans leur owner respectif lorsqu'un cas réel le justifie, pas comme dépendances implicites d'un consumer Interface.