v0.4.8-pre.015
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
<!-- file: docs/audits/V0_4_8_PRE_015_METADATA_TRANSVERSAL_RECONCILIATION_AUDIT.md -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Audit transversal Metadata `0.4.8-pre.015`
|
||||
|
||||
## 1. Objet
|
||||
|
||||
Cet audit ouvre la réconciliation transversale après la clôture de la finalisation desktop en `pre.014`. Il compare les trois domaines Metadata actifs :
|
||||
|
||||
- Metaplex Token Metadata ;
|
||||
- Token-2022 Token Metadata ;
|
||||
- Solana Program Metadata.
|
||||
|
||||
Le contrôle porte sur le stockage, les matrices contractuelles et réseau, les registres runtime, les exports publics et la nomenclature IDL. Il n’ouvre aucune nouvelle campagne Devnet et ne réinterprète pas les matrices historiques fermées.
|
||||
|
||||
## 2. Stockage
|
||||
|
||||
Les trois matérialisateurs Metadata produisent des `MtApiMaterializedOutput` de famille `Metadata`. Leur persistance passe par le stockage générique introduit par `0004_decode_materialization_store.sql` :
|
||||
|
||||
- `kb_sol_decode_events` conserve les observations décodées et leur payload JSONB ;
|
||||
- `kb_sol_mat_events` conserve les sorties matérialisées avec `processor_name`, `processor_version`, `input_key`, `output_key`, `materialized_family` et `payload_jsonb` ;
|
||||
- l’identité d’une projection est bornée par l’index unique `(processor_name, processor_version, input_key, output_key)` ;
|
||||
- les requêtes de lecture savent filtrer les sorties matérialisées par `processor_name`, `materialized_family` et signature.
|
||||
|
||||
Metaplex Token Metadata, Token-2022 Token Metadata et Solana Program Metadata n’exigent donc pas trois schémas spécialisés. Le nom du matérialiseur identifie le producteur et `payload_jsonb` conserve les projections hétérogènes sans perdre leur contrat métier.
|
||||
|
||||
**Conclusion stockage : aucune migration PostgreSQL n’est requise en `pre.015`.** Une table spécialisée ne serait justifiée que par un futur besoin de requête ou de contrainte relationnelle impossible à exprimer proprement avec le store générique actuel.
|
||||
|
||||
## 3. Matrices
|
||||
|
||||
### 3.1 Solana Program Metadata
|
||||
|
||||
Les matrices actives restent cohérentes entre elles :
|
||||
|
||||
| Matrice | Inventaire |
|
||||
|----------------------|------------------------------------:|
|
||||
| comptes | 3 entrées |
|
||||
| instructions stables | 9 |
|
||||
| exécuteur | 9 opérations |
|
||||
| matérialisation | 2 snapshots + 9 faits d’instruction |
|
||||
| pipeline | 9 opérations |
|
||||
| validation Devnet | 9 opérations `confirmed` |
|
||||
|
||||
La matrice Devnet conserve `0.4.8-pre.009` comme milestone propriétaire du contrat de scénarios, tandis que ses preuves pointent vers la campagne réelle `pre.010`. Ce découpage est codé explicitement dans le validateur et n’est pas une divergence à corriger.
|
||||
|
||||
### 3.2 Token-2022 Token Metadata
|
||||
|
||||
`SPL_TOKEN_2022_METADATA_DEVNET_VALIDATION_MATRIX.json` contient exactement les cinq opérations de `spl-token-metadata-interface` :
|
||||
|
||||
- `Initialize` ;
|
||||
- `UpdateField` ;
|
||||
- `Emit` ;
|
||||
- `RemoveKey` ;
|
||||
- `UpdateAuthority`.
|
||||
|
||||
Les cinq lignes sont `confirmed` sous le Program ID Token-2022. La matrice générale `SPL_TOKEN_2022_VALIDATION_MATRIX.json` reste un document historique du périmètre `0.4.6` et conserve volontairement ses scénarios réseau non exécutés de cette époque ; elle ne doit pas être réécrite à partir des preuves Metadata de `0.4.8`.
|
||||
|
||||
### 3.3 Metaplex Token Metadata
|
||||
|
||||
La matrice réseau courante ferme les 20 opérations :
|
||||
|
||||
- 15 `confirmed` ;
|
||||
- 5 `unavailable` ;
|
||||
- 0 `not_run`.
|
||||
|
||||
La matrice contractuelle `METAPLEX_TOKEN_METADATA_MATRIX.json` ferme parallèlement les 58 discriminateurs historiques :
|
||||
|
||||
- 20 `executable_current` ;
|
||||
- 15 `executable_deprecated` ;
|
||||
- 22 `decode_only_replaced` ;
|
||||
- 1 `decode_only_bridge_boundary`.
|
||||
|
||||
Son inventaire métier est correct, mais ses métadonnées de progression étaient restées sur l’ancien état `pre.003/pre.007` : phase d’exécution partielle, builders encore annoncés comme futurs et orchestration stateful encore listée dans `next_proofs`. Ces champs sont réconciliés avec la clôture réelle de `pre.013`, sans modifier les 58 lignes du contrat.
|
||||
|
||||
Les matrices `METAPLEX_TOKEN_METADATA_VALIDATION_MATRIX.json` (`0.4.7`) et `METAPLEX_TOKEN_METADATA_CROSS_VALIDATION_MATRIX.json` (`0.4.7-pre.010`) sont des corpus historiques fermés dont le validateur impose explicitement le milestone. Leurs statuts ne sont donc pas promus artificiellement à partir de la matrice réseau `pre.013`.
|
||||
|
||||
## 4. Registres runtime et exports
|
||||
|
||||
Le replay desktop enregistre explicitement les trois matérialisateurs :
|
||||
|
||||
- `MtMetadataMetaplexTokenMetadataMaterializer` ;
|
||||
- `MtMetadataSolanaProgramMaterializer` ;
|
||||
- `MtMetadataToken2022Materializer`.
|
||||
|
||||
Il enregistre également les décodeurs Metaplex Token Metadata, Solana Program Metadata et Token-2022. Les trois matérialisateurs sont exportés depuis la façade `kb-lib`.
|
||||
|
||||
`kb-pipeline` possède déjà des tests d’API externe dédiés aux pipelines Metaplex Token Metadata et Solana Program Metadata. La surface Token-2022 expose bien ses contrats stateful et Metadata depuis la racine de crate, mais ne possédait pas de test externe dédié dans `kb-pipeline/tests`.
|
||||
|
||||
**Correction `pre.015-delta` :** ajout d’un test externe Token-2022 Token Metadata couvrant la construction de la requête stateful et l’accessibilité crate-root des contrats `Emit` et de postcondition d’autorité.
|
||||
|
||||
## 5. IDL et nomenclature
|
||||
|
||||
Deux écarts documentaires actifs sont constatés :
|
||||
|
||||
1. le fichier Metaplex présent sous `idls/` est `metadata.metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s.metaplex_token_metadata.V1_14_0.from_github_mpl-token-metadata.json`, alors que `IDL_AUDIT.md` et `IDL_TO_KB_LIB_NOMENCLATURE.md` utilisaient encore le suffixe historique `from_solscan.json` ;
|
||||
2. la ligne Solana Program Metadata de la nomenclature indiquait encore « implémenter l’exécuteur », alors que modèles, décodeurs, matérialiseur, exécuteur, pipeline, scénarios et validation Devnet sont déjà présents.
|
||||
|
||||
Les deux documents sont corrigés. L’IDL JSON elle-même reste inchangée.
|
||||
|
||||
## 6. Changements du premier delta
|
||||
|
||||
Le premier delta de `pre.015` :
|
||||
|
||||
- passe `workspace.package.version` à `0.4.8-pre.15` ;
|
||||
- n’ajoute aucune migration de stockage ;
|
||||
- corrige les deux documents IDL ;
|
||||
- réconcilie uniquement les métadonnées de progression de la matrice contractuelle Metaplex active ;
|
||||
- ajoute le test d’API externe Token-2022 Token Metadata dans `kb-pipeline` ;
|
||||
- conserve les matrices historiques fermées sans réécriture ;
|
||||
- prépare la suite de la réconciliation avant `pre.016`.
|
||||
|
||||
## 7. Validation du delta initial
|
||||
|
||||
La validation locale du 9 août 2026 est complète :
|
||||
|
||||
- `cargo fmt --all` : terminé ;
|
||||
- `cargo check --workspace` : terminé ;
|
||||
- `cargo clippy --all-targets` : terminé sans warning ;
|
||||
- `python3 scripts/audit_rust_workspace_rules.py` : audits général, exports et workspace propres ;
|
||||
- `cargo test -p kb-pipeline` : 109 tests unitaires, trois tests d’API Metadata externes et doc-tests réussis ;
|
||||
- `cargo test -p kb-lib` : 706 tests unitaires, huit tests d’intégration et doc-tests réussis ;
|
||||
- `cargo test -p kb-pipeline-demo-scenarios` : 105 tests unitaires, 1 test CLI, 1 test API externe et doc-tests réussis.
|
||||
|
||||
Le test externe Token-2022 ajouté par le delta compile donc bien uniquement contre la façade publique de `kb-pipeline`.
|
||||
|
||||
## 8. Seconde passe — registres, exports et documentation active
|
||||
|
||||
Le registre desktop `demo_decode_replay` contient les trois matérialiseurs spécialisés et leurs identités exactes : Metaplex Token Metadata, Solana Program Metadata et Token-2022. Le test externe générique `kb-lib/tests/external_materializer_api.rs` impose déjà que les trois types satisfassent les façades publiques `MtApiEventMaterializer` et `MtMaterializer`.
|
||||
|
||||
L’exécuteur Solana Program Metadata possède déjà un test externe dédié, tandis que Metaplex n’avait qu’une couverture interne et des consommateurs workspace. `pre.015-delta-fix-001` ajoute donc un test downstream-style qui parcourt les 35 opérations supportées Metaplex via `ExMetadataMetaplexTokenMetadataExecutor`, vérifie les 15 codes deprecated et le refus d’un Program ID étranger, en n’utilisant que les exports crate-root.
|
||||
|
||||
Trois écarts de documentation active sont corrigés simultanément :
|
||||
|
||||
- le rustdoc public `EX_METAPLEX_TOKEN_METADATA_SUPPORTED_OPERATION_CODES` ne prétend plus être borné à `0.4.7-pre.005` ;
|
||||
- `kb-pipeline-demo-scenarios/USAGE.md` reflète les neuf opérations Solana Program Metadata `confirmed` de `pre.010` au lieu de présenter encore la matrice comme `not_run` ;
|
||||
- `docs/DEVNET_EXECUTION_GUIDE.md` remplace la « future fenêtre Metadata » et la section Metaplex hors ordre par un scénario Metadata on-chain unique, couvrant les trois domaines réellement exposés dans `demo_execution_metadata` et interdisant toujours le fetch off-chain.
|
||||
|
||||
`docs/README.md` référence désormais les rapports Devnet Token-2022 `pre.012`, Metaplex final `pre.013`, desktop Metadata `pre.014` et le présent audit `pre.015`.
|
||||
|
||||
La réconciliation des TODO retire également uniquement les tâches déjà closes : les validations Solana Program Metadata mainnet/Devnet/desktop et les anciennes fixtures Metaplex spécialisées. Les dettes `0.5.x`, ElGamal conditionnelles et les évolutions générales restent ouvertes.
|
||||
|
||||
## 9. Contrôles du correctif
|
||||
|
||||
Après application de `pre.015-delta-fix-001`, les validations locales minimales sont :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --all-targets
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
cargo test -p kb-lib
|
||||
```
|
||||
|
||||
Aucune campagne Devnet n’est requise : les changements réseau sont nuls et les statuts corrigés proviennent de matrices et rapports déjà qualifiés.
|
||||
|
||||
## 10. Validation de `pre.015-delta-fix-001`
|
||||
|
||||
La validation locale du 9 août 2026 confirme la seconde passe :
|
||||
|
||||
- `cargo fmt --all` : terminé ;
|
||||
- `cargo check --workspace` : terminé ;
|
||||
- `cargo clippy --all-targets` : terminé sans warning ;
|
||||
- `python3 scripts/audit_rust_workspace_rules.py` : audits général, exports et workspace propres ;
|
||||
- `cargo test -p kb-lib` : 706 tests unitaires, neuf tests d’intégration et doc-tests réussis.
|
||||
|
||||
Le nouveau test externe Metaplex `external_metaplex_token_metadata_executor_api` passe donc depuis un consommateur downstream-style utilisant uniquement les exports crate-root.
|
||||
|
||||
## 11. Conclusion
|
||||
|
||||
La réconciliation transversale ne laisse plus de divergence fonctionnelle active entre les trois domaines Metadata :
|
||||
|
||||
- aucune migration PostgreSQL spécialisée n’est requise ;
|
||||
- les matrices réseau courantes concordent avec les preuves qualifiées ;
|
||||
- les matrices historiques restent volontairement figées à leur milestone ;
|
||||
- les trois décodeurs et matérialiseurs sont présents dans les registres runtime attendus ;
|
||||
- les exports publics disposent de contrats externes cohérents ;
|
||||
- les références IDL et la nomenclature active sont réconciliées ;
|
||||
- les README, USAGE, TODO et guides actifs ne portent plus de statut Metadata devenu faux.
|
||||
|
||||
Deux tâches de niveau release restent volontairement hors de `pre.015` : transformer le ROADMAP pour refléter l’état final de `0.4.8` et mettre à jour le CHANGELOG général uniquement après la validation finale. Elles appartiennent explicitement à `pre.016` et ne constituent pas une divergence des contrats Metadata.
|
||||
|
||||
**Statut de `0.4.8-pre.015` : terminé et validé.** La suite peut ouvrir `0.4.8-pre.016`, réservé à la conformité finale, à la documentation de release, au nettoyage/archivage et à la préparation du prompt suivant.
|
||||
Reference in New Issue
Block a user