<!-- file: docs/architecture/SURFACE_CRATE_MATRIX.md -->
<!-- version: 4 -->

# Matrice des responsabilités par surface

## 1. Légende

- **Contrat/implémentation** : responsabilité métier principale.
- **Orchestration** : coordination entre couches.
- **Persistance** : stockage et replay.
- **Transport** : acquisition ou appel RPC.
- **Présentation** : UI ou adaptation de démonstration.

## 2. Matrice

| Surface                   | `ks-lib`                                                                       | `ks-pipeline`                                        | `ks-store`            | `ks-onchain-transport`        | `ks-pipeline-demo-scenarios`                           | `kb-app-demo-desktop`                               |
|---------------------------|--------------------------------------------------------------------------------|------------------------------------------------------|-----------------------|-------------------------------|--------------------------------------------------------|-----------------------------------------------------|
| Solana Core               | décodeurs, exécuteurs et matérialisateurs                                      | extraction, replay, stateful et exécution            | persistance générique | RPC HTTP/WS                   | validations Devnet                                     | panneaux fonctionnels                               |
| SPL Memo                  | décodage v1/v3/v4 ; exécution v4                                               | replay et exécution v4                               | persistance générique | RPC                           | scénario Memo v4                                       | panneau Memo v4                                     |
| SPL Token classique       | décodeur, exécuteur et matérialisateurs                                        | stateful, préflight et orchestration                 | persistance générique | RPC                           | scénarios Devnet                                       | panneaux fonctionnels                               |
| SPL ATA                   | décodeur, exécuteur et matérialisateurs                                        | stateful et orchestration                            | persistance générique | RPC                           | scénarios classique/Token-2022                         | panneaux fonctionnels                               |
| Token-2022                | décodeur, exécuteur et matérialisateurs                                        | corrélation, preuves, stateful, préflight et replay  | persistance générique | RPC                           | scénarios Devnet                                       | panneaux fonctionnels                               |
| Registre SPL ElGamal      | décodeur, exécuteur et matérialisation administrative                          | stateful et orchestration                            | persistance générique | acquisition de comptes et RPC | scénarios déclarés ; validation réseau réelle reportée | construction de plans et présentation               |
| Solana Program Metadata   | décodeur comptes/instructions, exécuteur et matérialiseur                      | stateful, préflight et orchestration d’exécution     | persistance générique | RPC et lectures de comptes    | 2 parcours Devnet ; 9 opérations `confirmed`           | campagne dédiée dans `demo_execution_metadata`      |
| Token-2022 Token Metadata | décodage interface/TLV, exécution des 5 opérations et matérialisation Metadata | stateful, préflight, replay et postconditions        | persistance générique | RPC et lectures de comptes    | campagne Devnet complète ; 5 opérations `confirmed`    | campagne dédiée dans `demo_execution_metadata`      |
| Metaplex Token Metadata   | décodeurs comptes/instructions, exécuteur courant/deprecated et matérialiseur  | stateful, préflight, orchestration et postconditions | persistance générique | RPC et lectures de comptes    | campagnes qualifiées ; 15 `confirmed`, 5 `unavailable` | campagnes qualifiées dans `demo_execution_metadata` |

## 3. Interprétation

Cette matrice décrit les responsabilités observées au niveau architectural. Elle ne déclare pas une couverture exhaustive de chaque instruction ou compte. La couverture détaillée reste démontrée par le code, les tests, les matrices sous `test-fixtures/contract-matrices/` et les rapports de validation actifs ou archivés.

La persistance des surfaces Metadata repose sur les contrats génériques de decode/materialization de `ks-store`. Leur séparation métier est portée notamment par les identités de processeur, les familles matérialisées, les clés de sortie et les payloads versionnés ; `0.4.8` n’introduit donc pas de schéma PostgreSQL spécialisé par protocole Metadata.

## 4. Statuts sensibles

- Memo v1 et v3 restent non exécutables ; Memo v4 est exécutable.
- Le registre SPL ElGamal est implémenté aux couches decoder/executor/stateful/materialization, mais ne doit pas être présenté comme validé sur Devnet ou Mainnet tant qu’une fixture réelle de preuve `PubkeyValidity` et de `Proof Context State` n’est pas disponible et confirmée.
- Solana Program Metadata est couvert par neuf opérations stables, toutes validées sur Devnet.
- Token-2022 Token Metadata est couvert par cinq opérations d’interface, toutes validées sur Devnet.
- Metaplex Token Metadata est clos pour la matrice courante de `0.4.8` avec 15 opérations `confirmed`, 5 `unavailable` et 0 `not_run` ; les opérations indisponibles ne doivent pas être promues sans nouvelle preuve réseau.
- La priorité trading des versions suivantes n’altère pas la vocation généraliste de `ks-lib` : les autres Program IDs restent dans le périmètre de couverture et peuvent être différés selon leur priorité de développement.