v0.1.0-pre.069

kb-lib/CHANGELOG.md

@@ -0,0 +1,42 @@
+<!-- file: kb-lib/CHANGELOG.md -->
+<!-- version: 2 -->
+
+# CHANGELOG — kb-lib
+
+## 0.1.0-pre.069-fix-001
+
+### Corrigé
+
+- suppression de la section `Non publié`, incompatible avec le rôle chronologique du changelog ;
+- retrait des limitations et travaux futurs du changelog ;
+- correction de la frontière entre historique, TODO et limites durables d’utilisation.
+
+### Documentation
+
+- réécriture de `TODO.md` sous forme de tâches uniquement ;
+- correction des exemples de `USAGE.md` afin de ne pas utiliser l’opérateur `?`.
+
+## 0.1.0-pre.069
+
+### Documentation
+
+- ajout de `README.md`, `TODO.md`, `USAGE.md` et du présent changelog selon les normes bot3.
+
+## 0.1.0
+
+### Migré
+
+- consolidation des modèles, décodeurs, exécuteurs et matérialisateurs issus de nombreuses crates bot2 dans une façade unique ;
+- migration des surfaces Solana Core, SPL Memo, SPL Token, SPL ATA, Token-2022, registre ElGamal et du décodeur Metaplex Token Metadata ;
+- migration des contrats de replay, de sécurité et de matérialisation.
+
+### Modifié
+
+- adoption de Rust 2024, de `#![forbid(unsafe_code)]`, `#![deny(unreachable_pub)]` et des conventions strictes d’exports, d’erreurs et de tracing ;
+- remplacement des anciennes frontières de crates par des modules privés et des réexports publics contrôlés.
+
+### Validation
+
+- tests unitaires des décodeurs, exécuteurs, matérialisateurs et contrats consolidés ;
+- matrices contractuelles chargées par les tests concernés ;
+- validations Devnet conservées pour les scénarios explicitement couverts pendant la migration.

kb-lib/README.md

@@ -1,148 +1,68 @@
 <!-- file: kb-lib/README.md -->
-<!-- version: 13 -->
+<!-- version: 14 -->
 
 # kb-lib
 
-`kb-lib` regroupe les modèles partagés et les composants de décodage, matérialisation et exécution de `khadhroony-bot3`. Les composants restent séparés par modules privés et sont exposés par la façade unique `kb-lib/src/lib.rs`.
+`kb-lib` est la bibliothèque fonctionnelle consolidée de `khadhroony-bot3`. Elle expose les modèles partagés, les contrats et implémentations de décodage, de matérialisation, d’exécution et de sécurité nécessaires au pipeline Solana.
 
-## Décodeur Solana Core
+## Périmètre
 
-`DcSolanaCoreDecoder` est le premier décodeur concret porté depuis bot2. Il implémente `DcApiInstructionDecoder` et `DcApiProtocolDecoder` sans dépendre de PostgreSQL, du RPC, de Tauri ou du wallet.
+La crate regroupe quatre familles internes, exposées par la façade `kb_lib` :
 
-Il couvre les 18 surfaces natives suivantes :
+- décodeurs et contrats de décodage contextualisé ;
+- exécuteurs, plans préparés et politiques de sécurité ;
+- matérialisateurs et projections structurées ;
+- modèles canoniques utilisés par les autres crates.
 
-- System Program ;
-- Compute Budget ;
-- Address Lookup Table ;
-- Config et Feature Gate ;
-- Vote et Stake ;
-- loaders natifs, BPF historiques, upgradeable et Loader v4 ;
-- précompiles Ed25519, secp256k1 et secp256r1 ;
-- Slashing ;
-- ZK ElGamal Proof et l’ancien ZK Token Proof.
+Elle couvre actuellement Solana Core, SPL Memo, SPL Token classique, SPL Associated Token Account, Token-2022, le registre SPL ElGamal et le décodeur Metaplex Token Metadata. De nombreux décodeurs et exécuteurs réservés exposent seulement une identité et une compatibilité conservatrice ; ils ne constituent pas une implémentation fonctionnelle.
 
-La matrice `docs/NATIVE_SOLANA_DECODER_MATRIX.json` reste la source machine-readable de la couverture. Les instructions inconnues, tronquées, historiques ou issues d’une transaction échouée conservent les statuts et diagnostics explicites définis par les contrats communs.
+## Responsabilités
 
-## Décodeur SPL Memo
+- reconnaître et décoder une instruction à partir d’un contexte canonique ;
+- publier des déclarations de couverture déterministes ;
+- produire des observations et diagnostics typés ;
+- construire des plans d’exécution bornés et vérifiables ;
+- appliquer les politiques de sécurité avant simulation, signature ou envoi ;
+- matérialiser les observations commitées selon des contrats explicites ;
+- conserver des modèles indépendants du stockage, du transport et de l’interface desktop.
 
-`DcSplMemoDecoder` couvre exactement les générations v1, v3 et v4. Le payload est lu comme un message brut sans discriminator, borné à 4 096 octets, puis projeté avec son texte UTF-8 complet, sa longueur, son SHA-256, les comptes ordonnés et le statut de commit.
+## Hors périmètre
 
-Memo v1 ignore les comptes lors de la validation runtime. Memo v3 et v4 exigent que chaque compte fourni soit signer. Les transactions échouées restent des intentions non commitées et les payloads UTF-8 invalides ou signatures manquantes deviennent des tentatives invalides explicites. La matrice normative est `docs/SPL_MEMO_MATRIX.json`.
+`kb-lib` ne persiste aucune donnée, ne dialogue pas directement avec un RPC, ne sélectionne pas un endpoint et ne gère pas les secrets de wallet. Ces responsabilités appartiennent respectivement à `kb-store`, `kb-onchain-transport`, `kb-pipeline` et `kb-wallet`.
 
-## Décodeur SPL Token classique
+## Surface publique principale
 
-`DcSplTokenDecoder` couvre exclusivement le Program ID classique
-`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`. Il publie 28 déclarations de couverture pour
-les tags `0..24`, `38`, `45` et `255`, y compris les variantes historiques, checked,
-`WithdrawExcessLamports`, `UnwrapLamports` et `Batch`.
+La façade publique est organisée autour de :
 
-Le parseur conserve les montants bruts sans perte, les comptes dans leur ordre d’origine, les
-formes d’autorité simple ou multisig, les suffixes runtime et les chemins outer/inner. Une
-transaction échouée reste une intention non commitée. `Batch` est borné à 64 enfants, 512 comptes
-cumulés et interdit les batches imbriqués. Le décodeur n’invente ni mint, ni decimals, ni état
-final ; les validations `M/N`, soldes et autorités existantes restent stateful. La matrice
-normative est `docs/SPL_TOKEN_MATRIX.json`.
+- `DcApiInstructionDecoder`, `DcApiProtocolDecoder` et les types `DcApi*` ;
+- les décodeurs concrets `DcSolanaCoreDecoder`, `DcSplMemoDecoder`, `DcSplTokenDecoder`, `DcSplAssociatedTokenAccountDecoder`, `DcSplToken2022Decoder`, `DcSplElgamalRegistryDecoder` et `DcMetadataMetaplexTokenMetadataDecoder` ;
+- `ExApiTypedInstructionExecutor`, `ExApiInstructionExecutor`, les politiques `ExApi*` et les exécuteurs concrets `Ex*Executor` ;
+- `ExSafetyChecker` et les décisions de sécurité associées ;
+- `MtApiEventMaterializer`, les types `MtApi*` et les matérialisateurs concrets ;
+- `MdCoreInstructionReplayInput` et les modèles canoniques réexportés.
 
-## Décodeur SPL Associated Token Account
+Le catalogue détaillé et les exemples se trouvent dans [USAGE.md](USAGE.md).
 
-`DcSplAssociatedTokenAccountDecoder` couvre exclusivement
-`ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL`. Il reconnaît les trois variantes publiées
-`Create`, `CreateIdempotent` et `RecoverNested`, ainsi que l’encodage historique vide de `Create`.
+## Matrices contractuelles
 
-Le décodeur conserve les comptes dans leur ordre original, leurs flags, doublons, chemins
-outer/inner et le statut de transaction. Il dérive les PDA avec l’ordre canonique
-`[wallet, token_program, mint]`, conserve simultanément l’adresse observée et l’adresse attendue,
-puis expose tout écart comme diagnostic. SPL Token classique et Token‑2022 sont distingués par leur
-Program ID sans reconstruire leur état ni interpréter leurs extensions. La matrice normative est
-`docs/SPL_ASSOCIATED_TOKEN_ACCOUNT_MATRIX.json`.
+Les matrices actives sont maintenues sous [`../test-fixtures/contract-matrices/`](../test-fixtures/contract-matrices/). Elles servent à la fois de références documentaires et de fixtures exécutées par des tests. Elles ne sont pas dupliquées dans la documentation de la crate.
 
-## Décodeur SPL Token‑2022
+## Relations
 
-`DcSplToken2022Decoder` couvre exclusivement
-`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`. Il conserve les 48 enveloppes de premier niveau,
-les sous-instructions d’extensions dont le wire est officiellement identifiable, les interfaces
-Token Metadata et Token Group exécutées directement par Token‑2022, ainsi que `Batch` sans batch
-imbriqué.
+- dépend de `kb-core` pour le contrat d’erreur commun ;
+- dépend de `kb-program-ids` pour le registre canonique des programmes ;
+- est consommée par `kb-pipeline`, `kb-store`, `kb-onchain-transport`, `kb-pipeline-demo-scenarios` et `kb-app-demo-desktop` ;
+- ne dépend jamais de `kb-store` ni d’une application.
 
-Le décodeur borne les payloads, les chaînes de metadata, le nombre d’enfants et les comptes
-cumulés. Les comptes, autorités, offsets de preuve, suffixes et chemins outer/inner restent
-ordonnés et exacts. Une transaction échouée produit une intention non commitée. Le parseur public
-`decoder_spl_token_2022_parse_token_2022_state()` distingue Mint, Account et Multisig, conserve la base exacte et expose
-les entrées TLV ordonnées sans inventer l’état d’un programme externe pointé. La matrice normative
-est `docs/SPL_TOKEN_2022_MATRIX.json`.
+## Statut et limites
 
-## Décodeur du registre ElGamal
+La migration des surfaces historiques jusqu’à un périmètre proche de bot2 `0.4.6` est largement réalisée. Le décodeur et les matérialisations Metaplex Token Metadata sont présents, mais l’exécuteur et la clôture fonctionnelle de cette surface restent à réaliser. Le registre ElGamal n’est pas déclaré validé sur Devnet ou Mainnet.
 
-`DcSplElgamalRegistryDecoder` couvre le programme indépendant
-`regVYJW7tcT8zipN5YiBvHsvR5jXW1uLFxaHSbugABg`. Il décode exactement `CreateRegistry` et
-`UpdateRegistry`, conserve l’offset relatif de preuve et ne prétend jamais vérifier la preuve ZK.
-`decoder_spl_elgamal_registry_parse_elgamal_registry_state()` exige exactement 64 octets et restitue le wallet propriétaire, la
-clé publique ElGamal et le wire complet. La matrice normative est
-`docs/SPL_ELGAMAL_REGISTRY_MATRIX.json`.
+## Documents
 
-## Décodeur Metaplex Token Metadata
-
-`DcMetadataMetaplexTokenMetadataDecoder` couvre exclusivement
-`metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s`. Il inventorie exactement les 58
-discriminateurs `0..=57`, conserve les arguments Borsh, les comptes positionnels,
-les placeholders optionnels, les chemins outer/CPI et les transactions échouées
-comme intentions non commitées.
-
-La façade `kb_lib` expose aussi les parseurs bornés des 15 variantes
-`Key 0..=14` : Metadata, Edition et Master Edition,
-Edition Marker V1/V2, Token Record, records de délégation et d’autorité, Token
-Owned Escrow et Reservation List historiques. Chaque parseur vérifie l’owner,
-le PDA, le bump, la longueur et les suffixes avant projection. Les comptes
-historiques gardent une provenance et un lifecycle matérialisables, mais une
-politique d’exécution définitivement interdite. La matrice normative est
-`docs/METAPLEX_TOKEN_METADATA_MATRIX.json`.
-
-## API publique utile
-
-- `MtApiEventMaterializer`, `MtApiMaterializerIdentity`, `MtApiMaterializationTransactionPolicy`, `MtApiMaterializerExecutionResult` et `MtApiMaterializedOutput` : contrat complet utilisable par un matérialiseur interne ou externe ;
-- `MtLifecycleMaterializer`, `MtAdminMaterializer`, `MtComplianceAuditMaterializer` et `MtStakingMaterializer` : matérialisateurs Solana natifs concrets ;
-- `materializer_admin_materialize_token_2022_state_snapshots()` et `materializer_admin_materialize_elgamal_registry_state_snapshot()` : projections stateful d’administration déjà exposées ;
-- `DcSolanaCoreDecoder` : décodeur concret natif ;
-- `DcSplMemoDecoder` : décodeur exact des trois générations SPL Memo ;
-- `DcSplTokenDecoder` : décodeur exact du programme SPL Token classique ;
-- `DcSplAssociatedTokenAccountDecoder` : décodeur exact du programme Associated Token Account ;
-- `DcSplToken2022Decoder` : décodeur exact des instructions Token‑2022 ;
-- `DcToken2022State`, `DcToken2022StateKind`, `DcToken2022TlvEntry` et `decoder_spl_token_2022_token_2022_state()` : API publique de lecture d’état Token‑2022 ;
-- `DcSplElgamalRegistryDecoder`, `DcSplElGamalRegistryState` et `decoder_spl_elgamal_registry_parse_elgamal_registry_state()` : API publique du registre ElGamal ;
-- `DcMetadataMetaplexTokenMetadataDecoder` : décodeur exact du programme Metaplex Token Metadata ;
-- les fonctions `decoder_metadata_metaplex_token_metadata_*` et les types `DcMetadataMtm*` : parseurs et snapshots publics des comptes Metaplex ;
-- les 98 types réservés `Dc*Decoder` : squelettes compatibles avec `DcApiProtocolDecoder`, exposant 97 Program IDs enregistrés et la frontière générique Anchor sans Program ID ;
-- `DcApiInstructionDecoder` : contrat de reconnaissance, couverture et décodage contextualisé ;
-- `DcApiProtocolDecoder` : contrat de compatibilité avec les observations historiques ;
-- `ExSolanaCoreExecutor`, `ExSolanaCoreExecutionIntent` et `ExSolanaCoreOperation` : exécuteur natif fonctionnel et contrat typé couvrant 109 opérations ;
-- les constantes `EX_SOLANA_CORE_*_OPERATION` : codes stables des opérations System, Compute Budget, ALT, précompiles, Config, Feature, Slashing, ZK ElGamal, Stake, Vote et Loaders ;
-- `ExSafetyChecker`, `ExSafetyDecision`, `ExSafetyEvaluation` et `ExSafetyViolation` : garde-fous communs avant simulation, signature et envoi ;
-- `ExSplMemoExecutor`, `ExSplMemoExecutionIntent` et `ExSplMemoOperation` : exécuteur SPL Memo v4 fonctionnel, avec v1/v3 explicitement decode-only ;
-- `ExApiTypedInstructionExecutor` et `ExApiInstructionExecutor` : contrat typé actuel et pont JSON historique de l’exécution ;
-- `MdCoreInstructionReplayInput` : input source-neutral produit par l’extraction core ;
-- `DcApiDecoderExecutionResult`, `DcApiDecoderRecognition` et `DcApiDecoderCoverageDeclaration` : résultats typés du pipeline ;
-- modèles canoniques et nomenclature réexportés depuis la façade.
-
-Les helpers, constantes wire et types intermédiaires de chaque composant restent internes. Leurs noms sont préfixés au niveau de la façade interne afin d’éviter les collisions lors de la fusion des anciens crates.
-
-## Exemple
-
-```rust
-let decoder = kb_lib::DcSolanaCoreDecoder;
-let recognition = kb_lib::DcApiInstructionDecoder::recognize(&decoder, &input);
-```
-
-L’appel de décodage complet utilise `DcApiInstructionDecoder::decode` après une reconnaissance compatible. Le pipeline demeure responsable de la sélection du décodeur et de la persistance du résultat.
-
-## Frontières
-
-- `kb-lib` ne dépend jamais de `kb-store`.
-- Les décodeurs ne lisent pas un état RPC courant pour reconstruire une transaction historique.
-- Une transaction échouée peut produire une intention structurée, jamais une mutation commitée.
-- Un matérialiseur externe dépend uniquement des contrats et modèles publics de `kb-lib`, jamais d’un décodeur concret.
-- Les squelettes réservés répondent uniquement `Maybe` pour leur Program ID et retournent une liste vide ; ils ne prétendent pas décoder une surface avant son port fonctionnel.
-- Les 102 squelettes d’exécuteurs encore réservés annoncent uniquement `Maybe` pour leurs Program IDs enregistrés et construisent un plan réservé à zéro instruction.
-- `ExSolanaCoreExecutor` annonce uniquement des capacités exactes `Supported` ou `Unsupported` et ne signe, n’envoie ni ne simule aucune transaction.
-- `ExSafetyChecker` évalue les plans et résultats de simulation sans effectuer lui-même d’appel RPC, de signature ou d’envoi.
-- `ExSplMemoExecutor` construit uniquement des plans ; il ne signe, n’envoie ni ne simule aucune transaction.
-- Les exécuteurs fonctionnels sont portés dans des tranches séparées, sans dépendre des décodeurs.
+- [Utilisation](USAGE.md)
+- [Travaux restants](TODO.md)
+- [Historique de la crate](CHANGELOG.md)
+- [Architecture générale](../docs/architecture/ARCHITECTURE.md)
+- [Pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md)
+- [Matrice des surfaces](../docs/architecture/SURFACE_CRATE_MATRIX.md)

kb-lib/TODO.md

@@ -0,0 +1,28 @@
+<!-- file: kb-lib/TODO.md -->
+<!-- version: 2 -->
+
+# TODO — kb-lib
+
+## Version 0.4.7 — Metaplex Token Metadata
+
+- [ ] vérifier la couverture exacte des matérialisations Metaplex Token Metadata migrées depuis bot2 ;
+- [ ] compléter uniquement les projections Metaplex réellement manquantes ;
+- [ ] implémenter l’exécuteur Metaplex Token Metadata à partir des contrats officiels vérifiés ;
+- [ ] ajouter les tests unitaires et contractuels de l’exécuteur ;
+- [ ] préparer les contrats nécessaires à l’intégration pipeline et aux démonstrations ;
+- [ ] valider le parcours d’exécution complet sur un réseau approprié lorsque les prérequis sont réunis.
+
+## Registre SPL ElGamal
+
+- [ ] confirmer si le registre est déployé et utilisable sur Devnet ou Mainnet ;
+- [ ] préparer une fixture de preuve `PubkeyValidity` et un compte `Proof Context State` valide si un réseau exploitable est confirmé ;
+- [ ] exécuter et documenter une validation réseau réelle avant de déclarer cette surface validée.
+
+## Surfaces ultérieures
+
+- [ ] remplacer les décodeurs et exécuteurs réservés par des implémentations bornées selon le ROADMAP ;
+- [ ] maintenir une façade publique lisible lors de chaque ajout de famille ;
+- [ ] vérifier que chaque type réservé reste explicitement non fonctionnel tant que sa surface n’est pas implémentée ;
+- [ ] documenter chaque nouvelle famille publique lors de son activation ;
+- [ ] maintenir les liens vers les matrices canoniques sans les dupliquer ;
+- [ ] implémenter l’infrastructure générique des conventions Anchor dans la série `0.6.x`.

kb-lib/USAGE.md

@@ -0,0 +1,120 @@
+<!-- file: kb-lib/USAGE.md -->
+<!-- version: 2 -->
+
+# Utilisation de kb-lib
+
+## Objectif
+
+Ce guide présente les familles d’API publiques significatives de `kb-lib`. Les helpers privés, éléments `pub(crate)` et modules non réexportés ne font pas partie du contrat consommateur.
+
+## Dépendance
+
+```toml
+[dependencies]
+kb-lib = { path = "../kb-lib" }
+```
+
+Toutes les fonctions retournant `kb_core::Result<T>` utilisent le contrat d’erreur structuré du workspace.
+
+## Décodage contextualisé
+
+`DcApiInstructionDecoder` définit la reconnaissance et le décodage d’une instruction contextualisée. Les décodeurs concrets sont des valeurs sans état.
+
+```rust
+use kb_lib::{DcApiInstructionDecoder, DcSolanaCoreDecoder};
+
+let decoder = DcSolanaCoreDecoder;
+let recognition = DcApiInstructionDecoder::recognize(&decoder, &input);
+let result = DcApiInstructionDecoder::decode(&decoder, &input);
+```
+
+Le consommateur doit vérifier le résultat typé et ses diagnostics. Une transaction échouée peut produire une intention structurée, mais pas une mutation committée.
+
+Décodeurs fonctionnels principaux :
+
+- `DcSolanaCoreDecoder` ;
+- `DcSplMemoDecoder` ;
+- `DcSplTokenDecoder` ;
+- `DcSplAssociatedTokenAccountDecoder` ;
+- `DcSplToken2022Decoder` ;
+- `DcSplElgamalRegistryDecoder` ;
+- `DcMetadataMetaplexTokenMetadataDecoder`.
+
+Les types réservés `Dc*Decoder` ne doivent pas être interprétés comme des décodeurs complets : ils publient une compatibilité conservatrice et aucune observation fonctionnelle.
+
+## Lecture d’états Token-2022 et ElGamal
+
+```rust
+let state = kb_lib::decoder_spl_token_2022_parse_token_2022_state(
+    &program_id,
+    &account_data,
+);
+let registry = kb_lib::decoder_spl_elgamal_registry_parse_elgamal_registry_state(
+    &account_data,
+);
+```
+
+Les parseurs vérifient les bornes et formats qu’ils annoncent. Ils ne reconstruisent pas un état historique depuis un RPC courant.
+
+## Comptes Metaplex Token Metadata
+
+Les fonctions `decoder_metadata_metaplex_token_metadata_decode_*_account` décodent les familles de comptes publiques prises en charge. Le consommateur doit fournir les données et le contexte attendus par la signature exacte de la fonction concernée. Les parseurs conservent les variantes historiques et refusent les longueurs, propriétaires ou suffixes incompatibles.
+
+## Exécution typée
+
+`ExApiTypedInstructionExecutor` produit un `ExApiPreparedExecutionPlan` à partir d’une intention et d’une politique explicites. Les exécuteurs concrets incluent notamment :
+
+- `ExSolanaCoreExecutor` ;
+- `ExSplMemoExecutor` pour Memo v4 ;
+- `ExSplTokenExecutor` ;
+- `ExSplAssociatedTokenAccountExecutor` ;
+- `ExSplToken2022Executor` ;
+- `ExSplElgamalRegistryExecutor`.
+
+```rust
+use kb_lib::{ExApiTypedInstructionExecutor, ExSplMemoExecutor};
+
+let executor = ExSplMemoExecutor;
+let plan = ExApiTypedInstructionExecutor::build_prepared_plan(
+    &executor,
+    &intent,
+    &policy,
+);
+```
+
+Le plan ne signe et n’envoie rien. La simulation, la confirmation opérateur, la soumission et la confirmation réseau appartiennent aux couches d’orchestration et de transport.
+
+Memo v1 et v3 restent non exécutables. Memo v4 est la seule génération exécutable.
+
+## Sécurité
+
+Les types `ExSafetyChecker`, `ExSafetyDecision`, `ExSafetyEvaluation` et `ExSafetyViolation` permettent d’évaluer un plan avant son utilisation. Une décision conservatrice doit être respectée par le consommateur ; elle ne doit pas être contournée par l’application.
+
+## Matérialisation
+
+`MtApiEventMaterializer` définit le contrat public de matérialisation. Les résultats `MtApiMaterializerExecutionResult` contiennent les sorties et diagnostics sans dépendre d’un backend de stockage.
+
+Les fonctions stateful publiques comprennent notamment :
+
+- `materializer_admin_materialize_token_2022_state_snapshots` ;
+- `materializer_admin_materialize_elgamal_registry_state_snapshot` ;
+- `materializer_token_materialize_token_2022_state_snapshot` ;
+- `materializer_metadata_materialize_token_2022_snapshot` ;
+- `materializer_metadata_materialize_metaplex_metadata_snapshot` ;
+- `materializer_metadata_materialize_metaplex_account_snapshot`.
+
+## Contrat de replay
+
+`MdCoreInstructionReplayInput` représente une instruction extraite avec son contexte transactionnel. Il constitue la frontière entre l’extraction Core, le pipeline de replay et les décodeurs.
+
+## Tests et matrices utiles
+
+Les tests unitaires du décodeur Metaplex et du décodeur Solana Core chargent directement certaines matrices de [`../test-fixtures/contract-matrices/`](../test-fixtures/contract-matrices/). Ils vérifient notamment l’égalité entre les entrées compilées et les contrats JSON, les discriminants, les bornes et les comportements historiques.
+
+Les tests des exécuteurs comparent les instructions produites aux builders officiels et vérifient signers, comptes ordonnés, coûts et politiques de sécurité.
+
+## Limites
+
+- aucune persistance ni acquisition réseau ;
+- aucun chargement dynamique des IDL en production ;
+- les squelettes réservés ne sont pas des implémentations ;