0.1.0

2026-07-23 16:37:12 +02:00
parent 99c345f2f2
commit 0da75c1311
2159 changed files with 230833 additions and 0 deletions
--- a/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/Cargo.toml
+++ b/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/Cargo.toml
@@ -0,0 +1,26 @@
+# file: kb_decoder_metadata_metaplex_token_metadata/Cargo.toml
+# version: 4
+
+[package]
+name = "kb_decoder_metadata_metaplex_token_metadata"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[dependencies]
+base64.workspace = true
+borsh_0_10.workspace = true
+kb_core = { path = "../kb_core" }
+kb_decoder_api = { path = "../kb_decoder_api" }
+kb_model = { path = "../kb_model" }
+kb_program_ids = { path = "../kb_program_ids" }
+kb_store_core = { path = "../kb_store_core" }
+mpl-token-metadata.workspace = true
+serde_json.workspace = true
+sha2.workspace = true
+solana-pubkey.workspace = true
+tracing.workspace = true
+
+[lints]
+workspace = true
--- a/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/README.md
+++ b/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/README.md
@@ -0,0 +1,178 @@
+<!-- file: kb_decoder_metadata_metaplex_token_metadata/README.md -->
+<!-- version: 31 -->
+
+# `kb_decoder_metadata_metaplex_token_metadata`
+
+Décodeur contextualisé dédié au programme Metaplex Token Metadata.
+
+La crate suit la frontière commune des décodeurs opérationnels du workspace :
+
+- `constants.rs` contient la surface, les discriminateurs, les bornes et la cible de tracing ;
+- `decoder.rs` implémente `ProtocolDecoder` et `InstructionDecoder` ;
+- `instruction.rs` contient le décodage Borsh borné, la résolution des comptes et les observations ;
+- `lib.rs` réexporte le décodeur d’instructions et les types publics du parseur de comptes ;
+- le Program ID provient exclusivement de `kb_program_ids`.
+
+`0.4.7-pre.002` active le décodage exact de `CreateMetadataAccountV3` et `UpdateMetadataAccountV2`. `0.4.7-pre.003` ajoute `VerifyCollection`, `UnverifyCollection` et `SetAndVerifyCollection`. `0.4.7-pre.004` ajoute le groupe sized `VerifySizedCollectionItem`, `UnverifySizedCollectionItem` et `SetAndVerifySizedCollectionItem`, avec la metadata de collection writable et le `collection_authority_record` optionnel. `0.4.7-pre.005` ajoute l’administration historique/courante des autorités de collection avec `ApproveCollectionAuthority` et `RevokeCollectionAuthority`, y compris le record PDA, les autorités distinctes et les comptes système/rent optionnels. `0.4.7-pre.006` ajoute les usages et autorités d’usage avec `ApproveUseAuthority`, `RevokeUseAuthority` et `Utilize`, leurs compteurs `u64`, le `use_authority_record`, le burner, les comptes Token/ATA et les comptes système/rent. `0.4.7-pre.007` ajoute `SignMetadata` et `UpdatePrimarySaleHappenedViaToken`, avec creator/owner signataires, metadata writable et token account readonly. Les layouts proviennent de `mpl-token-metadata 5.1.1`. Le décodeur préserve outer/CPI, statut de transaction, comptes ordonnés, paramètres Borsh, provenance et hash du wire. Il refuse les payloads tronqués, suffixes, comptes invalides et discriminateurs inconnus.
+
+Depuis `pre.025`, la crate traite le premier compte on-chain `MetadataV1`. Elle ne traite pas encore les autres comptes Metaplex Token Metadata, les metadata Token-2022 incorporées, Metaplex Core, Bubblegum ou les contenus JSON distants.
+
+## Groupe `0.4.7-pre.009`
+
+- `PuffMetadata` (`14`) : normalisation/padding de la metadata externe.
+- `RemoveCreatorVerification` (`28`) : retrait explicite de la vérification d’un creator.
+- `SetTokenStandard` (`35`) : classification du standard de token, avec edition optionnelle.
+
+Le décodage conserve les comptes ordonnés, les flags signer/writable officiels, outer/CPI, les échecs non committés et le rejet des suffixes.
+
+## 0.4.7-pre.009 — création metadata historique V2
+
+- `CreateMetadataAccountV2` (discriminant `16`) est décodé comme surface historique.
+- Le wire conserve `DataV2` et `is_mutable` avec les mêmes bornes que V3.
+- Le contrat de comptes reprend metadata, mint, mint authority, payer, update authority, System Program et rent optionnel.
+- Cette instruction est décodable et matérialisable ultérieurement, mais restera non exécutable.
+
+## 0.4.7-pre.010
+
+Ajout du décodage historique non exécutable de `CreateMetadataAccount` (0) et `UpdateMetadataAccount` (1), avec layouts `Data` V1 bornés et comptes exacts.
+
+## 0.4.7-pre.011
+
+Ajout de `CreateMasterEditionV3` (17) et `ConvertMasterEditionV1ToV2` (12). Le premier conserve `max_supply: Option<u64>` et les autorités/payer/programmes exacts ; le second est classé historique et conserve les trois comptes writable de conversion. Le mint d’éditions imprimées et les edition markers restent planifiés pour la tranche suivante.
+
+## 0.4.7-pre.012
+
+Ajout de `MintNewEditionFromMasterEditionViaToken` (11) et de la variante historique `MintNewEditionFromMasterEditionViaVaultProxy` (13). Les deux wires conservent l’édition `u64`, le master edition, le nouvel edition account et l’edition marker. La variante Token conserve le propriétaire et le token account du master ; la variante Vault conserve l’autorité, le safety deposit et le Token Vault Program. La variante Vault reste définitivement non exécutable.
+
+## 0.4.7-pre.013
+
+Ajout de `SetCollectionSize` (34) et `BubblegumSetCollectionSize` (36). Les deux wires conservent `size: u64`. La variante directe exige une collection authority writable/signataire ; la variante Bubblegum exige une collection authority readonly/signataire et le `bubblegum_signer` readonly/signataire. Le record d’autorité de collection reste optionnel. Le bridge Bubblegum est décodé avec provenance Metaplex Token Metadata mais reste distinct de la future couverture complète Bubblegum de `0.4.9`.
+
+## 0.4.7-pre.014 — Delegate / Revoke programmables
+
+- `Delegate` (44) et `Revoke` (45) décodés avec leurs enums Borsh exactes.
+- Contrat positionnel de 14 comptes conservé, y compris les placeholders Metaplex des comptes optionnels.
+- `AuthorizationData` est projeté lorsqu’il est présent ; validation sémantique différée au preflight stateful.
+
+## 0.4.7-pre.015 — lifecycle programmable
+
+Ajout de `Transfer` (49), `Lock` (46), `Unlock` (47), `Burn` (41) et `CloseAccounts` (57). Les enums Borsh modernes, comptes positionnels, placeholders optionnels, montants `u64`, outer/CPI et transactions échouées non committées sont conservés. La validation stateful des TokenRecord, rule sets, owners et PDA reste différée.
+
+## `0.4.7-pre.016` — audit exhaustif et freeze/thaw historiques
+
+- inventaire officiel recalé sur `clients/rust/src/generated/instructions/mod.rs` ;
+- ajout de `FreezeDelegatedAccount` (`26`) et `ThawDelegatedAccount` (`27`) ;
+- contrat exact de cinq comptes : delegate writable/signataire, token account writable, edition, mint et Token Program readonly ;
+- ces deux surfaces restent historiques, decode-only et non exécutables ;
+- les wrappers modernes et les opérations escrow/collect/resize/migrate encore absents restent explicitement planifiés avant le décodage des comptes.
+
+## `0.4.7-pre.017` — burns NFT historiques et printing token
+
+- `BurnNft` (`29`) conserve metadata, owner signataire, mint, token account, master edition, Token Program et collection metadata optionnelle.
+- `BurnEditionNft` (`37`) conserve le print mint, le master mint, leurs token accounts, les comptes edition/master edition et l’edition marker.
+- `DeprecatedMintNewEditionFromMasterEditionViaPrintingToken` (`3`) conserve les quinze comptes obligatoires et la reservation list optionnelle.
+- Ces trois surfaces sont historiques, decode-only et définitivement non exécutables.
+
+## `0.4.7-pre.018` — escrow et collecte
+
+- `CreateEscrowAccount` (`38`) et `CloseEscrowAccount` (`39`) conservent escrow, metadata, mint, token account, edition, payer et comptes système/sysvar exacts.
+- `TransferOutOfEscrow` (`40`) conserve `amount: u64`, les comptes source/destination de l’attribut, le mint et le token account liés à l’escrow, ainsi que l’autorité optionnelle.
+- `Collect` (`54`) conserve l’autorité signataire et le destinataire readonly.
+- Les quatre surfaces préservent outer/CPI et les transactions échouées non committées ; les owners, PDA et états escrow restent à valider lors du décodage stateful.
+
+## `0.4.7-pre.019` — wrapper moderne Create
+
+- `Create` (`42`) décode `CreateArgs::V1`, y compris metadata textuelle, royalties, creators, collection, uses, token standard, rule set, decimals et print supply.
+- Le contrat de neuf positions conserve metadata, master edition optionnelle, mint signataire/writable, authority, payer, update authority, programmes système/sysvar et SPL Token Program optionnel.
+- Les wrappers modernes `Create`, `Mint`, `Print`, `Update`, `Use`, `Verify`, `Unverify`, `Resize` et `Migrate` sont désormais décodés ; leurs validations owner/PDA restent stateful.
+
+## 0.4.7-pre.020
+
+Cette préversion ajoute le wrapper moderne `Mint` (`43`). Le décodeur conserve `MintArgs::V1`, le montant brut `u64`, `AuthorizationData` optionnelle et les quinze positions officielles, y compris les placeholders Metaplex utilisés pour les comptes optionnels absents. L’activation runtime, la validation stateful des PDA/rule sets et l’exécution restent différées.
+
+## `0.4.7-pre.021` — wrapper moderne Print
+
+- `Print` (`55`) décode les variantes `PrintArgs::V1` et `PrintArgs::V2`, chacune conservant le numéro d’édition `u64`.
+- Le contrat de dix-huit positions conserve les comptes edition metadata, edition, edition mint, token account, Token Record optionnel, master edition, edition marker, payer, propriétaire du master token account et programmes Token/ATA/System/Sysvar.
+- `PrintV1` et `PrintV2` sont des builders spécialisés du même discriminant `55` et non deux discriminateurs supplémentaires.
+- Les PDA edition/edition marker et les owners restent à valider lors du décodage stateful des comptes.
+
+## Update moderne
+
+Le discriminant `50` décode `UpdateArgs` et toutes ses variantes publiées : `V1`, `AsUpdateAuthorityV2`, `AsAuthorityItemDelegateV2`, `AsCollectionDelegateV2`, `AsDataDelegateV2`, `AsProgrammableConfigDelegateV2`, `AsDataItemDelegateV2`, `AsCollectionItemDelegateV2` et `AsProgrammableConfigItemDelegateV2`. Le contrat conserve onze positions, avec placeholders Metaplex readonly pour les comptes optionnels absents. La validation sémantique des PDA, delegates, owners et rule sets reste stateful.
+
+## Wrapper Use et vérifications modernes
+
+`Use` (`51`) décode `UseArgs::V1` et ses douze positions. `Verify` (`52`) et `Unverify` (`53`) décodent `VerificationArgs::{CreatorV1,CollectionV1}` avec huit positions et placeholders optionnels explicites. Les validations owner/PDA restent stateful.
+
+## `0.4.7-pre.024` — inventaire d’instructions exhaustif
+
+`Resize` (`56`) et `Migrate` (`48`) sont décodés avec leurs contrats positionnels exacts. L’audit de l’IDL `1.14.0` a également identifié puis couvert les six discriminateurs historiques manquants `2`, `5`, `6`, `8`, `9` et `10`. Le registre contient désormais les 58 discriminateurs `0..=57` sans trou. Ces six surfaces historiques restent decode-only et non exécutables.
+
+## `0.4.7-pre.025` — premier compte on-chain
+
+La crate expose désormais `decode_metadata_account` pour le layout officiel `Metadata`. Le parseur refuse un owner étranger avant désérialisation, exige `Key::MetadataV1`, borne les données et les champs textuels, limite les creators, valide le PDA canonique `[metadata, program_id, mint]` et conserve le bump. Cette tranche ne couvre pas encore MasterEdition, Edition, EditionMarker, TokenRecord ni les records de délégation.
+
+## `0.4.7-pre.026` — comptes edition et master edition
+
+La crate expose `decode_edition_account` pour `DeprecatedMasterEditionV1`, `MasterEditionV2` et `EditionV1`. Le décodeur vérifie l’owner avant parsing, exige le PDA commun `[metadata, program_id, mint, edition]`, conserve le bump et projette supply/max supply, printing mints historiques, parent et numéro d’édition. `MasterEditionV1` reste historique et decode-only ; `MasterEditionV2` et `EditionV1` alimenteront les futures projections stateful.
+
+## `0.4.7-pre.027` — Edition Marker V1/V2
+
+- `EditionMarker` conserve un ledger fixe de 31 octets, soit 248 éditions par groupe.
+- Le groupe V1 est `edition / 248` et le PDA utilise les seeds `[metadata, program_id, mint, edition, groupe_decimal]`.
+- `EditionMarkerV2` conserve un `Vec<u8>` extensible et utilise un PDA unique `[metadata, program_id, mint, edition, marker]`.
+- Le décodeur projette l'index d'octet, le masque big-endian et l'état `edition_taken` pour l'édition demandée.
+- V1 exige exactement 32 octets ; V2 exige une longueur Borsh exacte et borne le ledger à 1 048 576 octets.
+- Owner étranger, mauvais PDA, discriminant inconnu, troncature et suffixe sont refusés avant toute projection stateful.
+
+## `0.4.7-pre.028` — Token Record programmable
+
+- `TokenRecord` exige le layout alloué exact de 80 octets et `Key::TokenRecord`.
+- Le PDA est dérivé par `[metadata, program_id, mint, token_record, token_account]` et le bump stocké doit être identique au bump canonique.
+- La projection conserve `TokenState::{Unlocked,Locked,Listed}`, la révision optionnelle du rule set, le delegate, son rôle et la destination optionnelle de locked transfer.
+- Les rôles officiels `Sale`, `Transfer`, `Utility`, `Staking`, `Standard`, `LockedTransfer` et `Migration` sont conservés sans normalisation destructive.
+- Owner étranger, mauvais PDA, bump incohérent, mauvais discriminant, troncature et suffixe sont refusés.
+
+## `0.4.7-pre.029` — records de délégation et d’autorité
+
+- `MetadataDelegateRecord` et `HolderDelegateRecord` exigent exactement 98 octets, leur discriminant `Key`, leur bump stocké et leur PDA canonique.
+- Les huit seeds de rôles Metadata sont conservées sans regroupement : `authority_item_delegate`, `collection_delegate`, `use_delegate`, `data_delegate`, `programmable_config_delegate`, `data_item_delegate`, `collection_item_delegate` et `prog_config_item_delegate`.
+- `HolderDelegateRecord` conserve le rôle `print_delegate`, le holder utilisé comme seed, le delegate et l’update authority stockée.
+- `CollectionAuthorityRecord` valide `[metadata, program_id, mint, collection_authority, authority]` et conserve l’update authority optionnelle.
+- `UseAuthorityRecord` valide `[metadata, program_id, mint, user, authority]`, exige exactement 10 octets et conserve `allowed_uses: u64`.
+- Owner étranger, longueur incorrecte, discriminant erroné, PDA ou bump incohérents sont refusés avant projection.
+
+## `0.4.7-pre.030` — Token Owned Escrow stateful
+
+- `TokenOwnedEscrow` conserve le base token mint, l’autorité `TokenOwner` ou `Creator(Pubkey)` et le bump stocké.
+- Le PDA `TokenOwner` utilise `[metadata, program_id, base_token, 0, escrow]`.
+- Le PDA `Creator` utilise `[metadata, program_id, base_token, 1, creator, escrow]`.
+- Les longueurs Borsh exactes sont 35 octets pour `TokenOwner` et 67 octets pour `Creator`.
+- Owner étranger, discriminant, longueur, PDA ou bump incohérents sont refusés.
+- Les effets de `CreateEscrowAccount`, `CloseEscrowAccount`, `TransferOutOfEscrow`, `Migrate` et `Resize` sont décrits dans la matrice pour la future corrélation stateful ; ils ne sont pas encore matérialisés.
+
+## `0.4.7-pre.031` — Reservation Lists historiques
+
+- `ReservationListV1` conserve le Master Edition, le supply snapshot optionnel et jusqu’à 200 entrées avec compteurs `u8`.
+- `ReservationListV2` conserve les mêmes identités, des compteurs `u64` et les caches `total_reservation_spots`/`current_reservation_spots`.
+- Le PDA exige le contexte `resource` et suit `[metadata, program_id, master_edition, reservation, resource]`.
+- Les tailles maximales historiques sont 6 949 octets pour V1 et 9 749 octets pour V2 ; seuls les suffixes de padding nuls sont tolérés.
+- Ces comptes sont historiques et ne seront jamais exposés par l’exécuteur. Ils restent toutefois matérialisables comme état historique lors des backfills et replays, avec provenance explicite et sans écraser l’état actif.
+
+## `0.4.7-pre.032` — audit exhaustif des comptes
+
+- Les quinze variantes `Key` publiées, de `Uninitialized` (`0`) à `HolderDelegate` (`14`), sont inventoriées dans le code et la matrice.
+- Les quatorze variantes représentant un compte réel sont reliées à un décodeur borné ; `Uninitialized` est une sentinelle explicitement rejetée.
+- Les layouts historiques restent `decode-only`, `EditionMarkerV2` reste classé actif/expérimental, et les comptes actifs restent éligibles aux futures matérialisations.
+- Un test compare l’ordre et les discriminateurs Borsh du SDK épinglé à l’inventaire interne et à `docs/METAPLEX_TOKEN_METADATA_MATRIX.json`.
+- Toute variante future absente de l’inventaire doit faire échouer l’audit avant toute activation runtime.
+
+## `0.4.7-pre.033` — modèle canonique et provenance
+
+- Chaque snapshot de compte est enveloppé dans une identité stable `program_id:account_address`, un nom de layout, son discriminant `Key` exact et une version canonique interne.
+- Les layouts sont classés `Active`, `ActiveExperimental` ou `Historical` sans confondre cette classification avec leur politique d’exécution.
+- Les états actifs et expérimentaux sont matérialisables comme état courant ; les états historiques sont matérialisables comme état historique lors d’un backfill ou replay.
+- Les layouts historiques restent définitivement non exécutables, même lorsqu’ils sont matérialisés.
+- La provenance conserve source, slot, write version, signature, index outer/inner et statut committed lorsque ces données sont disponibles.
+- Les sources `Live`, `Replay`, `Backfill`, `Repair` et `Synthetic` restent distinctes afin d’éviter toute fusion silencieuse des observations.
--- a/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/account.rs
+++ b/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/account.rs
--- a/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/canonical.rs
+++ b/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/canonical.rs
@@ -0,0 +1,417 @@
+// file: kb_decoder_metadata_metaplex_token_metadata/src/canonical.rs
+// version: 2
+
+//! Canonical Metaplex account identities, provenance and materialization policy.
+
+/// Lifecycle class of one decoded Metaplex account layout.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CanonicalAccountLifecycle {
+    /// Current account layout used by supported runtime flows.
+    Active,
+    /// Published account layout whose runtime surface is still experimental.
+    ActiveExperimental,
+    /// Historical account layout retained for ledger replay and backfill.
+    Historical,
+}
+
+/// Materialization policy attached to one canonical account snapshot.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CanonicalMaterializationPolicy {
+    /// Materialize the latest committed state of an active account.
+    ActiveState,
+    /// Materialize historical state with explicit lifecycle provenance.
+    HistoricalState,
+}
+
+/// Execution policy attached to one canonical account layout.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CanonicalExecutionPolicy {
+    /// The layout belongs to current operations that may later be executable.
+    CurrentCandidate,
+    /// The layout belongs to an experimental operation requiring explicit activation.
+    ExperimentalCandidate,
+    /// Historical state must never be exposed by an executor.
+    NeverHistorical,
+}
+
+/// Origin of one canonical account observation.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CanonicalObservationSource {
+    /// Account observed from a live subscription or direct live read.
+    Live,
+    /// Account reconstructed while replaying already stored transactions.
+    Replay,
+    /// Account discovered while backfilling historical ledger data.
+    Backfill,
+    /// Account read to repair a detected ingestion gap.
+    Repair,
+    /// Synthetic account used only by bounded validation tests.
+    Synthetic,
+}
+
+/// Provenance retained for one canonical account observation.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CanonicalAccountProvenance {
+    /// Observation source.
+    pub source: CanonicalObservationSource,
+    /// Slot associated with the account state when known.
+    pub slot: std::option::Option<u64>,
+    /// Provider write version when available.
+    pub write_version: std::option::Option<u64>,
+    /// Transaction signature responsible for the state when known.
+    pub signature: std::option::Option<String>,
+    /// Instruction index associated with the mutation when known.
+    pub instruction_index: std::option::Option<u32>,
+    /// Inner-instruction index associated with the mutation when known.
+    pub inner_instruction_index: std::option::Option<u32>,
+    /// Whether the source state is committed according to the caller's boundary.
+    pub committed: bool,
+}
+
+/// Stable identity and policy of one canonical Metaplex account snapshot.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct CanonicalAccountIdentity {
+    /// Stable identity formed from program id and canonical account address.
+    pub stable_id: String,
+    /// Canonical Metaplex Token Metadata program id.
+    pub program_id: String,
+    /// Canonical account address.
+    pub account: String,
+    /// Published layout name.
+    pub layout: String,
+    /// Exact published `Key` discriminant.
+    pub discriminant: u8,
+    /// Internal canonical-model version.
+    pub canonical_version: u16,
+    /// Published lifecycle class.
+    pub lifecycle: CanonicalAccountLifecycle,
+    /// Materialization policy, including historical backfill state.
+    pub materialization: CanonicalMaterializationPolicy,
+    /// Execution policy separated from materialization.
+    pub execution: CanonicalExecutionPolicy,
+}
+
+/// Typed state carried by one canonical Metaplex account snapshot.
+#[derive(Clone, Debug, PartialEq)]
+pub enum CanonicalMetadataAccountState {
+    /// Metadata account state.
+    Metadata(crate::MetadataAccountSnapshot),
+    /// Master Edition or printed Edition state.
+    Edition(crate::EditionAccountSnapshot),
+    /// Edition Marker state.
+    EditionMarker(crate::EditionMarkerAccountSnapshot),
+    /// Programmable Token Record state.
+    TokenRecord(crate::TokenRecordAccountSnapshot),
+    /// Metadata or holder delegate state.
+    DelegateRecord(crate::DelegateRecordAccountSnapshot),
+    /// Collection or use authority state.
+    AuthorityRecord(crate::AuthorityRecordAccountSnapshot),
+    /// Token-owned escrow state.
+    TokenOwnedEscrow(crate::TokenOwnedEscrowAccountSnapshot),
+    /// Historical Reservation List state.
+    ReservationList(crate::ReservationListAccountSnapshot),
+}
+
+/// Canonical envelope used by future materializers and stateful replay.
+#[derive(Clone, Debug, PartialEq)]
+pub struct CanonicalMetadataAccountSnapshot {
+    /// Stable identity and lifecycle policy.
+    pub identity: CanonicalAccountIdentity,
+    /// Observation provenance.
+    pub provenance: CanonicalAccountProvenance,
+    /// Typed bounded state.
+    pub state: CanonicalMetadataAccountState,
+}
+
+fn canonical_identity(
+    account: &str,
+    layout: &str,
+    discriminant: u8,
+    lifecycle: CanonicalAccountLifecycle,
+) -> CanonicalAccountIdentity {
+    let program_id = kb_program_ids::METADATA_METAPLEX_TOKEN_METADATA_PROGRAM_ID.to_string();
+    let materialization = match lifecycle {
+        CanonicalAccountLifecycle::Historical => CanonicalMaterializationPolicy::HistoricalState,
+        CanonicalAccountLifecycle::Active | CanonicalAccountLifecycle::ActiveExperimental => {
+            CanonicalMaterializationPolicy::ActiveState
+        },
+    };
+    let execution = match lifecycle {
+        CanonicalAccountLifecycle::Historical => CanonicalExecutionPolicy::NeverHistorical,
+        CanonicalAccountLifecycle::Active => CanonicalExecutionPolicy::CurrentCandidate,
+        CanonicalAccountLifecycle::ActiveExperimental => {
+            CanonicalExecutionPolicy::ExperimentalCandidate
+        },
+    };
+    return CanonicalAccountIdentity {
+        stable_id: format!("{program_id}:{account}"),
+        program_id,
+        account: account.to_string(),
+        layout: layout.to_string(),
+        discriminant,
+        canonical_version: 1,
+        lifecycle,
+        materialization,
+        execution,
+    };
+}
+
+impl CanonicalMetadataAccountSnapshot {
+    /// Wraps one Metadata account snapshot with stable identity and provenance.
+    pub fn from_metadata(
+        snapshot: crate::MetadataAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "MetadataV1",
+            mpl_token_metadata::types::Key::MetadataV1 as u8,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::Metadata(snapshot),
+        };
+    }
+
+    /// Wraps one Edition or Master Edition snapshot with exact lifecycle policy.
+    pub fn from_edition(
+        snapshot: crate::EditionAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant, lifecycle) = match snapshot.kind {
+            crate::EditionAccountKind::MasterEditionV1 => (
+                "MasterEditionV1",
+                mpl_token_metadata::types::Key::MasterEditionV1 as u8,
+                CanonicalAccountLifecycle::Historical,
+            ),
+            crate::EditionAccountKind::MasterEditionV2 => (
+                "MasterEditionV2",
+                mpl_token_metadata::types::Key::MasterEditionV2 as u8,
+                CanonicalAccountLifecycle::Active,
+            ),
+            crate::EditionAccountKind::EditionV1 => (
+                "EditionV1",
+                mpl_token_metadata::types::Key::EditionV1 as u8,
+                CanonicalAccountLifecycle::Active,
+            ),
+        };
+        let identity = canonical_identity(&snapshot.account, layout, discriminant, lifecycle);
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::Edition(snapshot),
+        };
+    }
+
+    /// Wraps one Edition Marker snapshot with exact lifecycle policy.
+    pub fn from_edition_marker(
+        snapshot: crate::EditionMarkerAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant, lifecycle) = match snapshot.kind {
+            crate::EditionMarkerAccountKind::EditionMarkerV1 => (
+                "EditionMarker",
+                mpl_token_metadata::types::Key::EditionMarker as u8,
+                CanonicalAccountLifecycle::Active,
+            ),
+            crate::EditionMarkerAccountKind::EditionMarkerV2 => (
+                "EditionMarkerV2",
+                mpl_token_metadata::types::Key::EditionMarkerV2 as u8,
+                CanonicalAccountLifecycle::ActiveExperimental,
+            ),
+        };
+        let identity = canonical_identity(&snapshot.account, layout, discriminant, lifecycle);
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::EditionMarker(snapshot),
+        };
+    }
+
+    /// Wraps one Token Record snapshot.
+    pub fn from_token_record(
+        snapshot: crate::TokenRecordAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "TokenRecord",
+            mpl_token_metadata::types::Key::TokenRecord as u8,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::TokenRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Metadata or Holder Delegate snapshot.
+    pub fn from_delegate_record(
+        snapshot: crate::DelegateRecordAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant) = if snapshot.kind == "MetadataDelegateRecord" {
+            ("MetadataDelegate", mpl_token_metadata::types::Key::MetadataDelegate as u8)
+        } else {
+            ("HolderDelegate", mpl_token_metadata::types::Key::HolderDelegate as u8)
+        };
+        let identity = canonical_identity(
+            &snapshot.account,
+            layout,
+            discriminant,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::DelegateRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Collection or Use Authority snapshot.
+    pub fn from_authority_record(
+        snapshot: crate::AuthorityRecordAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant) = if snapshot.kind == "CollectionAuthorityRecord" {
+            (
+                "CollectionAuthorityRecord",
+                mpl_token_metadata::types::Key::CollectionAuthorityRecord as u8,
+            )
+        } else {
+            ("UseAuthorityRecord", mpl_token_metadata::types::Key::UseAuthorityRecord as u8)
+        };
+        let identity = canonical_identity(
+            &snapshot.account,
+            layout,
+            discriminant,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::AuthorityRecord(snapshot),
+        };
+    }
+
+    /// Wraps one Token Owned Escrow snapshot.
+    pub fn from_token_owned_escrow(
+        snapshot: crate::TokenOwnedEscrowAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let identity = canonical_identity(
+            &snapshot.account,
+            "TokenOwnedEscrow",
+            mpl_token_metadata::types::Key::TokenOwnedEscrow as u8,
+            CanonicalAccountLifecycle::Active,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::TokenOwnedEscrow(snapshot),
+        };
+    }
+
+    /// Wraps one historical Reservation List snapshot as materializable historical state.
+    pub fn from_reservation_list(
+        snapshot: crate::ReservationListAccountSnapshot,
+        provenance: CanonicalAccountProvenance,
+    ) -> Self {
+        let (layout, discriminant) = match snapshot.kind {
+            crate::ReservationListAccountKind::V1 => {
+                ("ReservationListV1", mpl_token_metadata::types::Key::ReservationListV1 as u8)
+            },
+            crate::ReservationListAccountKind::V2 => {
+                ("ReservationListV2", mpl_token_metadata::types::Key::ReservationListV2 as u8)
+            },
+        };
+        let identity = canonical_identity(
+            &snapshot.account,
+            layout,
+            discriminant,
+            CanonicalAccountLifecycle::Historical,
+        );
+        return Self {
+            identity,
+            provenance,
+            state: CanonicalMetadataAccountState::ReservationList(snapshot),
+        };
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn historical_state_is_materializable_but_never_executable() {
+        let snapshot = crate::ReservationListAccountSnapshot {
+            account: "reservation-account".to_string(),
+            bump: 1,
+            kind: crate::ReservationListAccountKind::V1,
+            master_edition: "master-edition".to_string(),
+            resource: "resource".to_string(),
+            supply_snapshot: std::option::Option::Some(7),
+            reservations: std::vec::Vec::new(),
+            total_reservation_spots: 0,
+            current_reservation_spots: 0,
+            payload_json: serde_json::json!({}),
+        };
+        let provenance = super::CanonicalAccountProvenance {
+            source: super::CanonicalObservationSource::Backfill,
+            slot: std::option::Option::Some(42),
+            write_version: std::option::Option::None,
+            signature: std::option::Option::Some("historical-signature".to_string()),
+            instruction_index: std::option::Option::Some(3),
+            inner_instruction_index: std::option::Option::None,
+            committed: true,
+        };
+        let canonical =
+            super::CanonicalMetadataAccountSnapshot::from_reservation_list(snapshot, provenance);
+        assert_eq!(canonical.identity.lifecycle, super::CanonicalAccountLifecycle::Historical);
+        assert_eq!(
+            canonical.identity.materialization,
+            super::CanonicalMaterializationPolicy::HistoricalState
+        );
+        assert_eq!(canonical.identity.execution, super::CanonicalExecutionPolicy::NeverHistorical);
+        assert_eq!(canonical.provenance.source, super::CanonicalObservationSource::Backfill);
+        assert!(canonical.identity.stable_id.ends_with(":reservation-account"));
+    }
+
+    #[test]
+    fn active_and_experimental_layouts_keep_distinct_policies() {
+        let metadata = crate::MetadataAccountSnapshot {
+            account: "metadata-account".to_string(),
+            bump: 1,
+            mint: "mint".to_string(),
+            update_authority: "authority".to_string(),
+            name: "name".to_string(),
+            symbol: "symbol".to_string(),
+            uri: "uri".to_string(),
+            seller_fee_basis_points: 0,
+            primary_sale_happened: false,
+            is_mutable: true,
+            payload_json: serde_json::json!({}),
+        };
+        let provenance = super::CanonicalAccountProvenance {
+            source: super::CanonicalObservationSource::Live,
+            slot: std::option::Option::Some(1),
+            write_version: std::option::Option::Some(2),
+            signature: std::option::Option::None,
+            instruction_index: std::option::Option::None,
+            inner_instruction_index: std::option::Option::None,
+            committed: true,
+        };
+        let canonical =
+            super::CanonicalMetadataAccountSnapshot::from_metadata(metadata, provenance);
+        assert_eq!(canonical.identity.lifecycle, super::CanonicalAccountLifecycle::Active);
+        assert_eq!(
+            canonical.identity.materialization,
+            super::CanonicalMaterializationPolicy::ActiveState
+        );
+        assert_eq!(canonical.identity.execution, super::CanonicalExecutionPolicy::CurrentCandidate);
+        assert_eq!(canonical.identity.discriminant, 4);
+        assert_eq!(canonical.identity.canonical_version, 1);
+    }
+}
--- a/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/constants.rs
+++ b/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/constants.rs
@@ -0,0 +1,258 @@
+// file: kb_decoder_metadata_metaplex_token_metadata/src/constants.rs
+// version: 28
+
+//! Internal constants for Metaplex Token Metadata decoding.
+
+/// Stable decoder surface code.
+pub(crate) const SURFACE_CODE: &str = "metadata_metaplex_token_metadata";
+/// Tracing target for this decoder.
+/// Maximum retained instruction payload size.
+pub(crate) const MAX_INSTRUCTION_BYTES: usize = 16_384;
+/// Maximum encoded base64 instruction payload size.
+pub(crate) const MAX_BASE64_BYTES: usize = 21_852;
+/// Maximum number of instruction accounts accepted by this decoder.
+pub(crate) const MAX_INSTRUCTION_ACCOUNTS: usize = 64;
+/// Number of bytes retained in malformed-wire diagnostics.
+pub(crate) const DIAGNOSTIC_PREFIX_BYTES: usize = 32;
+/// Stable event payload contract version.
+pub(crate) const EVENT_VERSION: u32 = 1;
+/// Deprecated Create Master Edition discriminator.
+pub(crate) const DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR: u8 = 2;
+/// Deprecated Set Reservation List discriminator.
+pub(crate) const DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR: u8 = 5;
+/// Deprecated Create Reservation List discriminator.
+pub(crate) const DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR: u8 = 6;
+/// Deprecated Mint Printing Tokens Via Token discriminator.
+pub(crate) const DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR: u8 = 8;
+/// Deprecated Mint Printing Tokens discriminator.
+pub(crate) const DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR: u8 = 9;
+/// Historical Create Master Edition discriminator.
+pub(crate) const CREATE_MASTER_EDITION_DISCRIMINATOR: u8 = 10;
+/// Deprecated printing-token mint-new-edition discriminator.
+pub(crate) const DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR: u8 = 3;
+/// Historical Create Metadata Account discriminator.
+pub(crate) const CREATE_METADATA_ACCOUNT_DISCRIMINATOR: u8 = 0;
+/// Historical Update Metadata Account discriminator.
+pub(crate) const UPDATE_METADATA_ACCOUNT_DISCRIMINATOR: u8 = 1;
+/// Historical Create Metadata Account V2 discriminator.
+pub(crate) const CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR: u8 = 16;
+/// Create Metadata Account V3 discriminator.
+pub(crate) const CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR: u8 = 33;
+/// Update Metadata Account V2 discriminator.
+pub(crate) const UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR: u8 = 15;
+/// Verify Collection discriminator.
+pub(crate) const VERIFY_COLLECTION_DISCRIMINATOR: u8 = 18;
+/// Unverify Collection discriminator.
+pub(crate) const UNVERIFY_COLLECTION_DISCRIMINATOR: u8 = 22;
+/// Set And Verify Collection discriminator.
+pub(crate) const SET_AND_VERIFY_COLLECTION_DISCRIMINATOR: u8 = 25;
+/// Approve Collection Authority discriminator.
+pub(crate) const APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR: u8 = 23;
+/// Revoke Collection Authority discriminator.
+pub(crate) const REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR: u8 = 24;
+/// Verify Sized Collection Item discriminator.
+pub(crate) const VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 30;
+/// Unverify Sized Collection Item discriminator.
+pub(crate) const UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 31;
+/// Set And Verify Sized Collection Item discriminator.
+pub(crate) const SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR: u8 = 32;
+/// Sign Metadata discriminator.
+pub(crate) const SIGN_METADATA_DISCRIMINATOR: u8 = 7;
+/// Update Primary Sale Happened Via Token discriminator.
+pub(crate) const UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR: u8 = 4;
+/// Utilize discriminator.
+pub(crate) const UTILIZE_DISCRIMINATOR: u8 = 19;
+/// Approve Use Authority discriminator.
+pub(crate) const APPROVE_USE_AUTHORITY_DISCRIMINATOR: u8 = 20;
+/// Revoke Use Authority discriminator.
+pub(crate) const REVOKE_USE_AUTHORITY_DISCRIMINATOR: u8 = 21;
+/// Puff Metadata discriminator.
+pub(crate) const PUFF_METADATA_DISCRIMINATOR: u8 = 14;
+/// Freeze Delegated Account discriminator.
+pub(crate) const FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR: u8 = 26;
+/// Thaw Delegated Account discriminator.
+pub(crate) const THAW_DELEGATED_ACCOUNT_DISCRIMINATOR: u8 = 27;
+/// Remove Creator Verification discriminator.
+pub(crate) const REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR: u8 = 28;
+/// Set Token Standard discriminator.
+pub(crate) const SET_TOKEN_STANDARD_DISCRIMINATOR: u8 = 35;
+/// Mint New Edition From Master Edition Via Token discriminator.
+pub(crate) const MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR: u8 = 11;
+/// Mint New Edition From Master Edition Via Vault Proxy discriminator.
+pub(crate) const MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR: u8 = 13;
+/// Convert Master Edition V1 to V2 discriminator.
+pub(crate) const CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR: u8 = 12;
+/// Create Master Edition V3 discriminator.
+pub(crate) const CREATE_MASTER_EDITION_V3_DISCRIMINATOR: u8 = 17;
+/// Set Collection Size discriminator.
+pub(crate) const SET_COLLECTION_SIZE_DISCRIMINATOR: u8 = 34;
+/// Bubblegum Set Collection Size discriminator.
+pub(crate) const BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR: u8 = 36;
+/// Create Escrow Account discriminator.
+pub(crate) const CREATE_ESCROW_ACCOUNT_DISCRIMINATOR: u8 = 38;
+/// Close Escrow Account discriminator.
+pub(crate) const CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR: u8 = 39;
+/// Transfer Out Of Escrow discriminator.
+pub(crate) const TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR: u8 = 40;
+/// Collect discriminator.
+pub(crate) const COLLECT_DISCRIMINATOR: u8 = 54;
+/// Historical Burn NFT discriminator.
+pub(crate) const BURN_NFT_DISCRIMINATOR: u8 = 29;
+/// Historical Burn Edition NFT discriminator.
+pub(crate) const BURN_EDITION_NFT_DISCRIMINATOR: u8 = 37;
+/// Burn discriminator.
+pub(crate) const BURN_DISCRIMINATOR: u8 = 41;
+/// Lock discriminator.
+pub(crate) const LOCK_DISCRIMINATOR: u8 = 46;
+/// Unlock discriminator.
+pub(crate) const UNLOCK_DISCRIMINATOR: u8 = 47;
+/// Transfer discriminator.
+pub(crate) const TRANSFER_DISCRIMINATOR: u8 = 49;
+/// Close Accounts discriminator.
+pub(crate) const CLOSE_ACCOUNTS_DISCRIMINATOR: u8 = 57;
+/// Modern Create discriminator.
+pub(crate) const CREATE_DISCRIMINATOR: u8 = 42;
+/// Modern Mint discriminator.
+pub(crate) const MINT_DISCRIMINATOR: u8 = 43;
+/// Modern Print discriminator.
+pub(crate) const PRINT_DISCRIMINATOR: u8 = 55;
+/// Modern Update discriminator.
+pub(crate) const UPDATE_DISCRIMINATOR: u8 = 50;
+/// Modern Use discriminator.
+pub(crate) const USE_DISCRIMINATOR: u8 = 51;
+/// Modern Verify discriminator.
+pub(crate) const VERIFY_DISCRIMINATOR: u8 = 52;
+/// Modern Unverify discriminator.
+pub(crate) const UNVERIFY_DISCRIMINATOR: u8 = 53;
+/// Migrate discriminator.
+pub(crate) const MIGRATE_DISCRIMINATOR: u8 = 48;
+/// Resize discriminator.
+pub(crate) const RESIZE_DISCRIMINATOR: u8 = 56;
+/// Delegate discriminator.
+pub(crate) const DELEGATE_DISCRIMINATOR: u8 = 44;
+/// Revoke discriminator.
+pub(crate) const REVOKE_DISCRIMINATOR: u8 = 45;
+/// Current pre-release instruction inventory.
+pub(crate) const INSTRUCTION_ENTRIES: &[(u8, &str, bool)] = &[
+    (CREATE_METADATA_ACCOUNT_DISCRIMINATOR, "create_metadata_account", true),
+    (
+        DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR,
+        "deprecated_create_master_edition",
+        true,
+    ),
+    (
+        DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR,
+        "deprecated_mint_new_edition_from_master_edition_via_printing_token",
+        true,
+    ),
+    (UPDATE_METADATA_ACCOUNT_DISCRIMINATOR, "update_metadata_account", true),
+    (
+        UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR,
+        "update_primary_sale_happened_via_token",
+        false,
+    ),
+    (
+        DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR,
+        "deprecated_set_reservation_list",
+        true,
+    ),
+    (
+        DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR,
+        "deprecated_create_reservation_list",
+        true,
+    ),
+    (SIGN_METADATA_DISCRIMINATOR, "sign_metadata", false),
+    (
+        DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR,
+        "deprecated_mint_printing_tokens_via_token",
+        true,
+    ),
+    (
+        DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR,
+        "deprecated_mint_printing_tokens",
+        true,
+    ),
+    (CREATE_MASTER_EDITION_DISCRIMINATOR, "create_master_edition", true),
+    (PUFF_METADATA_DISCRIMINATOR, "puff_metadata", false),
+    (
+        MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR,
+        "mint_new_edition_from_master_edition_via_token",
+        false,
+    ),
+    (
+        MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR,
+        "mint_new_edition_from_master_edition_via_vault_proxy",
+        true,
+    ),
+    (
+        CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR,
+        "convert_master_edition_v1_to_v2",
+        true,
+    ),
+    (UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR, "update_metadata_account_v2", false),
+    (CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR, "create_metadata_account_v2", true),
+    (CREATE_MASTER_EDITION_V3_DISCRIMINATOR, "create_master_edition_v3", false),
+    (CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR, "create_metadata_account_v3", false),
+    (VERIFY_COLLECTION_DISCRIMINATOR, "verify_collection", false),
+    (UNVERIFY_COLLECTION_DISCRIMINATOR, "unverify_collection", false),
+    (SET_AND_VERIFY_COLLECTION_DISCRIMINATOR, "set_and_verify_collection", false),
+    (
+        APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR,
+        "approve_collection_authority",
+        false,
+    ),
+    (REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR, "revoke_collection_authority", false),
+    (
+        VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "verify_sized_collection_item",
+        false,
+    ),
+    (
+        UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "unverify_sized_collection_item",
+        false,
+    ),
+    (
+        SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR,
+        "set_and_verify_sized_collection_item",
+        false,
+    ),
+    (UTILIZE_DISCRIMINATOR, "utilize", false),
+    (APPROVE_USE_AUTHORITY_DISCRIMINATOR, "approve_use_authority", false),
+    (REVOKE_USE_AUTHORITY_DISCRIMINATOR, "revoke_use_authority", false),
+    (FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR, "freeze_delegated_account", true),
+    (THAW_DELEGATED_ACCOUNT_DISCRIMINATOR, "thaw_delegated_account", true),
+    (REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR, "remove_creator_verification", false),
+    (SET_TOKEN_STANDARD_DISCRIMINATOR, "set_token_standard", false),
+    (SET_COLLECTION_SIZE_DISCRIMINATOR, "set_collection_size", false),
+    (
+        BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR,
+        "bubblegum_set_collection_size",
+        false,
+    ),
+    (CREATE_ESCROW_ACCOUNT_DISCRIMINATOR, "create_escrow_account", false),
+    (CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR, "close_escrow_account", false),
+    (TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR, "transfer_out_of_escrow", false),
+    (BURN_NFT_DISCRIMINATOR, "burn_nft", true),
+    (BURN_EDITION_NFT_DISCRIMINATOR, "burn_edition_nft", true),
+    (BURN_DISCRIMINATOR, "burn", false),
+    (CREATE_DISCRIMINATOR, "create", false),
+    (MINT_DISCRIMINATOR, "mint", false),
+    (LOCK_DISCRIMINATOR, "lock", false),
+    (UNLOCK_DISCRIMINATOR, "unlock", false),
+    (TRANSFER_DISCRIMINATOR, "transfer", false),
+    (COLLECT_DISCRIMINATOR, "collect", false),
+    (PRINT_DISCRIMINATOR, "print", false),
+    (UPDATE_DISCRIMINATOR, "update", false),
+    (USE_DISCRIMINATOR, "use", false),
+    (VERIFY_DISCRIMINATOR, "verify", false),
+    (UNVERIFY_DISCRIMINATOR, "unverify", false),
+    (MIGRATE_DISCRIMINATOR, "migrate", false),
+    (RESIZE_DISCRIMINATOR, "resize", false),
+    (CLOSE_ACCOUNTS_DISCRIMINATOR, "close_accounts", false),
+    (DELEGATE_DISCRIMINATOR, "delegate", false),
+    (REVOKE_DISCRIMINATOR, "revoke", false),
+];
+
+/// Canonical tracing target for this crate.
+pub(crate) const TRACING_TARGET: &str = "kb_decoder_metadata_metaplex_token_metadata";
--- a/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/decoder.rs
+++ b/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/decoder.rs
--- a/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/instruction.rs
+++ b/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/instruction.rs
--- a/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/lib.rs
+++ b/migration/khadhroony-bot2-reference/kb_decoder_metadata_metaplex_token_metadata/src/lib.rs
@@ -0,0 +1,226 @@
+// file: kb_decoder_metadata_metaplex_token_metadata/src/lib.rs
+// version: 17
+
+//! Contextual instruction and bounded account decoder for Metaplex Token Metadata.
+#![warn(missing_docs)]
+#![deny(unreachable_pub)]
+#![forbid(unsafe_code)]
+
+mod account;
+mod canonical;
+mod constants;
+mod decoder;
+mod instruction;
+
+/// Approve Collection Authority discriminator.
+pub(crate) use crate::constants::APPROVE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Approve Use Authority discriminator.
+pub(crate) use crate::constants::APPROVE_USE_AUTHORITY_DISCRIMINATOR;
+/// Bubblegum Set Collection Size discriminator.
+pub(crate) use crate::constants::BUBBLEGUM_SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Burn discriminator.
+pub(crate) use crate::constants::BURN_DISCRIMINATOR;
+/// Historical Burn Edition NFT discriminator.
+pub(crate) use crate::constants::BURN_EDITION_NFT_DISCRIMINATOR;
+/// Historical Burn NFT discriminator.
+pub(crate) use crate::constants::BURN_NFT_DISCRIMINATOR;
+/// Close Accounts discriminator.
+pub(crate) use crate::constants::CLOSE_ACCOUNTS_DISCRIMINATOR;
+/// Close Escrow Account discriminator.
+pub(crate) use crate::constants::CLOSE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Collect discriminator.
+pub(crate) use crate::constants::COLLECT_DISCRIMINATOR;
+/// Convert Master Edition V1 to V2 discriminator.
+pub(crate) use crate::constants::CONVERT_MASTER_EDITION_V1_TO_V2_DISCRIMINATOR;
+/// Modern Create discriminator.
+pub(crate) use crate::constants::CREATE_DISCRIMINATOR;
+/// Create Escrow Account discriminator.
+pub(crate) use crate::constants::CREATE_ESCROW_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Master Edition discriminator.
+pub(crate) use crate::constants::CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Create Master Edition V3 discriminator.
+pub(crate) use crate::constants::CREATE_MASTER_EDITION_V3_DISCRIMINATOR;
+/// Historical Create Metadata Account discriminator.
+pub(crate) use crate::constants::CREATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Historical Create Metadata Account V2 discriminator.
+pub(crate) use crate::constants::CREATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Create Metadata Account V3 discriminator.
+pub(crate) use crate::constants::CREATE_METADATA_ACCOUNT_V3_DISCRIMINATOR;
+/// Delegate discriminator.
+pub(crate) use crate::constants::DELEGATE_DISCRIMINATOR;
+/// Deprecated Create Master Edition discriminator.
+pub(crate) use crate::constants::DEPRECATED_CREATE_MASTER_EDITION_DISCRIMINATOR;
+/// Deprecated Create Reservation List discriminator.
+pub(crate) use crate::constants::DEPRECATED_CREATE_RESERVATION_LIST_DISCRIMINATOR;
+/// Deprecated printing-token mint-new-edition discriminator.
+pub(crate) use crate::constants::DEPRECATED_MINT_NEW_EDITION_VIA_PRINTING_TOKEN_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens discriminator.
+pub(crate) use crate::constants::DEPRECATED_MINT_PRINTING_TOKENS_DISCRIMINATOR;
+/// Deprecated Mint Printing Tokens Via Token discriminator.
+pub(crate) use crate::constants::DEPRECATED_MINT_PRINTING_TOKENS_VIA_TOKEN_DISCRIMINATOR;
+/// Deprecated Set Reservation List discriminator.
+pub(crate) use crate::constants::DEPRECATED_SET_RESERVATION_LIST_DISCRIMINATOR;
+/// Number of bytes retained in malformed-wire diagnostics.
+pub(crate) use crate::constants::DIAGNOSTIC_PREFIX_BYTES;
+/// Stable event payload contract version.
+pub(crate) use crate::constants::EVENT_VERSION;
+/// Freeze Delegated Account discriminator.
+pub(crate) use crate::constants::FREEZE_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Current pre-release instruction inventory.
+pub(crate) use crate::constants::INSTRUCTION_ENTRIES;
+/// Lock discriminator.
+pub(crate) use crate::constants::LOCK_DISCRIMINATOR;
+/// Maximum encoded base64 instruction payload size.
+pub(crate) use crate::constants::MAX_BASE64_BYTES;
+/// Maximum number of instruction accounts accepted by this decoder.
+pub(crate) use crate::constants::MAX_INSTRUCTION_ACCOUNTS;
+/// Tracing target for this decoder.
+/// Maximum retained instruction payload size.
+pub(crate) use crate::constants::MAX_INSTRUCTION_BYTES;
+/// Migrate discriminator.
+pub(crate) use crate::constants::MIGRATE_DISCRIMINATOR;
+/// Modern Mint discriminator.
+pub(crate) use crate::constants::MINT_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Token discriminator.
+pub(crate) use crate::constants::MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_TOKEN_DISCRIMINATOR;
+/// Mint New Edition From Master Edition Via Vault Proxy discriminator.
+pub(crate) use crate::constants::MINT_NEW_EDITION_FROM_MASTER_EDITION_VIA_VAULT_PROXY_DISCRIMINATOR;
+/// Modern Print discriminator.
+pub(crate) use crate::constants::PRINT_DISCRIMINATOR;
+/// Puff Metadata discriminator.
+pub(crate) use crate::constants::PUFF_METADATA_DISCRIMINATOR;
+/// Remove Creator Verification discriminator.
+pub(crate) use crate::constants::REMOVE_CREATOR_VERIFICATION_DISCRIMINATOR;
+/// Resize discriminator.
+pub(crate) use crate::constants::RESIZE_DISCRIMINATOR;
+/// Revoke Collection Authority discriminator.
+pub(crate) use crate::constants::REVOKE_COLLECTION_AUTHORITY_DISCRIMINATOR;
+/// Revoke discriminator.
+pub(crate) use crate::constants::REVOKE_DISCRIMINATOR;
+/// Revoke Use Authority discriminator.
+pub(crate) use crate::constants::REVOKE_USE_AUTHORITY_DISCRIMINATOR;
+/// Set And Verify Collection discriminator.
+pub(crate) use crate::constants::SET_AND_VERIFY_COLLECTION_DISCRIMINATOR;
+/// Set And Verify Sized Collection Item discriminator.
+pub(crate) use crate::constants::SET_AND_VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Set Collection Size discriminator.
+pub(crate) use crate::constants::SET_COLLECTION_SIZE_DISCRIMINATOR;
+/// Set Token Standard discriminator.
+pub(crate) use crate::constants::SET_TOKEN_STANDARD_DISCRIMINATOR;
+/// Sign Metadata discriminator.
+pub(crate) use crate::constants::SIGN_METADATA_DISCRIMINATOR;
+/// Stable decoder surface code.
+pub(crate) use crate::constants::SURFACE_CODE;
+/// Thaw Delegated Account discriminator.
+pub(crate) use crate::constants::THAW_DELEGATED_ACCOUNT_DISCRIMINATOR;
+/// Canonical tracing target for this crate.
+pub(crate) use crate::constants::TRACING_TARGET;
+/// Transfer discriminator.
+pub(crate) use crate::constants::TRANSFER_DISCRIMINATOR;
+/// Transfer Out Of Escrow discriminator.
+pub(crate) use crate::constants::TRANSFER_OUT_OF_ESCROW_DISCRIMINATOR;
+/// Unlock discriminator.
+pub(crate) use crate::constants::UNLOCK_DISCRIMINATOR;
+/// Unverify Collection discriminator.
+pub(crate) use crate::constants::UNVERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Unverify discriminator.
+pub(crate) use crate::constants::UNVERIFY_DISCRIMINATOR;
+/// Unverify Sized Collection Item discriminator.
+pub(crate) use crate::constants::UNVERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Modern Update discriminator.
+pub(crate) use crate::constants::UPDATE_DISCRIMINATOR;
+/// Historical Update Metadata Account discriminator.
+pub(crate) use crate::constants::UPDATE_METADATA_ACCOUNT_DISCRIMINATOR;
+/// Update Metadata Account V2 discriminator.
+pub(crate) use crate::constants::UPDATE_METADATA_ACCOUNT_V2_DISCRIMINATOR;
+/// Update Primary Sale Happened Via Token discriminator.
+pub(crate) use crate::constants::UPDATE_PRIMARY_SALE_HAPPENED_VIA_TOKEN_DISCRIMINATOR;
+/// Modern Use discriminator.
+pub(crate) use crate::constants::USE_DISCRIMINATOR;
+/// Utilize discriminator.
+pub(crate) use crate::constants::UTILIZE_DISCRIMINATOR;
+/// Verify Collection discriminator.
+pub(crate) use crate::constants::VERIFY_COLLECTION_DISCRIMINATOR;
+/// Modern Verify discriminator.
+pub(crate) use crate::constants::VERIFY_DISCRIMINATOR;
+/// Verify Sized Collection Item discriminator.
+pub(crate) use crate::constants::VERIFY_SIZED_COLLECTION_ITEM_DISCRIMINATOR;
+/// Crate-root access to `ParsedInstruction` from `instruction`.
+pub(crate) use crate::instruction::ParsedInstruction;
+/// Crate-root access to `decode` from `instruction`.
+pub(crate) use crate::instruction::decode;
+/// Crate-root access to `entry_for_discriminator` from `instruction`.
+pub(crate) use crate::instruction::entry_for_discriminator;
+/// Crate-root access to `payload_discriminator` from `instruction`.
+pub(crate) use crate::instruction::payload_discriminator;
+
+/// Canonical projection shared by Collection and Use Authority records.
+pub use crate::account::AuthorityRecordAccountSnapshot;
+/// Canonical projection shared by Metadata and Holder delegate records.
+pub use crate::account::DelegateRecordAccountSnapshot;
+/// Supported edition account layout.
+pub use crate::account::EditionAccountKind;
+/// Canonical bounded projection of one edition or master-edition account.
+pub use crate::account::EditionAccountSnapshot;
+/// Supported Edition Marker account layout.
+pub use crate::account::EditionMarkerAccountKind;
+/// Canonical bounded projection of one Edition Marker account.
+pub use crate::account::EditionMarkerAccountSnapshot;
+/// Exhaustive published Metaplex account-key inventory.
+pub use crate::account::METADATA_ACCOUNT_LAYOUT_AUDIT;
+/// Bounded error returned while decoding a Metadata account.
+pub use crate::account::MetadataAccountDecodeError;
+/// One entry in the exhaustive published account-key audit.
+pub use crate::account::MetadataAccountLayoutAuditEntry;
+/// Canonical bounded projection of one Metadata account.
+pub use crate::account::MetadataAccountSnapshot;
+/// One bounded historical reservation entry.
+pub use crate::account::ReservationEntrySnapshot;
+/// Historical Reservation List account generation.
+pub use crate::account::ReservationListAccountKind;
+/// Canonical decode-only projection of a historical Reservation List account.
+pub use crate::account::ReservationListAccountSnapshot;
+/// Canonical projection of one Token Owned Escrow account.
+pub use crate::account::TokenOwnedEscrowAccountSnapshot;
+/// Authority form used by one Token Owned Escrow account.
+pub use crate::account::TokenOwnedEscrowAuthorityKind;
+/// Canonical bounded projection of one programmable Token Record account.
+pub use crate::account::TokenRecordAccountSnapshot;
+/// Decodes one Collection Authority Record account.
+pub use crate::account::decode_collection_authority_record_account;
+/// Decodes and validates one edition or master-edition account snapshot.
+pub use crate::account::decode_edition_account;
+/// Decodes and validates one Edition Marker account snapshot.
+pub use crate::account::decode_edition_marker_account;
+/// Decodes one Holder Delegate Record account.
+pub use crate::account::decode_holder_delegate_record_account;
+/// Decodes and validates one canonical Metadata account snapshot.
+pub use crate::account::decode_metadata_account;
+/// Decodes one Metadata Delegate Record account.
+pub use crate::account::decode_metadata_delegate_record_account;
+/// Decodes one historical Reservation List V1 or V2 account.
+pub use crate::account::decode_reservation_list_account;
+/// Decodes one Token Owned Escrow account.
+pub use crate::account::decode_token_owned_escrow_account;
+/// Decodes and validates one programmable Token Record account snapshot.
+pub use crate::account::decode_token_record_account;
+/// Decodes one Use Authority Record account.
+pub use crate::account::decode_use_authority_record_account;
+/// Stable identity and policy of one canonical account snapshot.
+pub use crate::canonical::CanonicalAccountIdentity;
+/// Lifecycle class of one canonical account layout.
+pub use crate::canonical::CanonicalAccountLifecycle;
+/// Provenance retained for one canonical account observation.
+pub use crate::canonical::CanonicalAccountProvenance;
+/// Execution policy separated from historical materialization.
+pub use crate::canonical::CanonicalExecutionPolicy;
+/// Materialization policy for active or historical state.
+pub use crate::canonical::CanonicalMaterializationPolicy;
+/// Canonical account envelope used by materializers and replay.
+pub use crate::canonical::CanonicalMetadataAccountSnapshot;
+/// Typed canonical Metaplex account state.
+pub use crate::canonical::CanonicalMetadataAccountState;
+/// Origin of one canonical account observation.
+pub use crate::canonical::CanonicalObservationSource;
+/// Exact Metaplex Token Metadata decoder.
+pub use crate::decoder::MetadataMetaplexTokenMetadataDecoder;