0.1.0

docs/NOMENCLATURE.md

@@ -0,0 +1,106 @@
+<!-- file: docs/NOMENCLATURE.md -->
+<!-- version: 4 -->
+
+# Nomenclature
+
+Ce document fixe les noms internes utilisés dans le workspace.
+
+## Programmes
+
+- `program_id` : adresse Solana réelle.
+- `program_code` : nom interne stable du programme.
+- `protocol_code` : famille protocolaire.
+- `surface_code` : surface concrète.
+
+## Événements
+
+Le format canonique est :
+
+```text
+<surface_code>.<event_name>
+```
+
+Exemples :
+
+```text
+pump_swap.buy
+raydium_amm_v4.swap_base_in
+meteora_dlmm.swap
+jupiter_v6.route
+```
+
+## Tables Solana PostgreSQL
+
+Les tables Solana PostgreSQL utilisent le schéma courant du profil PostgreSQL, généralement `public`. Le projet ne crée pas de schémas applicatifs `raw`, `core`, `obs`, `decode`, `mat`, `catalog`, `agg`, `ops` ou `wallet`.
+
+Le format canonique est :
+
+```text
+kb_sol_<domain>_<name>
+```
+
+Domaines autorisés au départ :
+
+```text
+raw
+core
+obs
+decode
+mat
+catalog
+agg
+ops
+wallet
+```
+
+Exemples valides :
+
+```text
+kb_sol_raw_transactions
+kb_sol_core_transactions
+kb_sol_obs_transaction_observations
+kb_sol_obs_program_observations
+kb_sol_decode_decoded_events
+kb_sol_mat_trade_events
+kb_sol_catalog_tokens
+kb_sol_ops_processing_ledger
+```
+
+Exemples interdits, écrits avec `DOT` pour que les audits textuels simples ne confondent pas documentation et usage réel :
+
+```text
+raw DOT kb_sol_rpc_transactions
+core DOT kb_sol_transactions
+obs DOT kb_sol_program_observations
+decode DOT kb_sol_decoded_events
+mat DOT kb_sol_trade_events
+catalog DOT kb_sol_tokens
+ops DOT kb_sol_processing_ledger
+```
+
+## Surfaces de programmes
+
+Le nom canonique d'une surface de programme doit suivre le format :
+
+```text
+<function_code>_<family_code>_<identifier_code>[_vN]
+```
+
+Le nom de crate correspondant doit suivre le format :
+
+```text
+kb_decoder_<function_code>_<family_code>_<identifier_code>[_vN]
+```
+
+Les anciens noms issus des IDL, des explorateurs ou des anciennes matrices doivent être conservés dans le registre sous `source_code` ou `normalized_code`, mais ne doivent pas être utilisés comme nouvelle référence stable si un nom canonique existe.
+
+Voir aussi :
+
+- `docs/DATABASE.md` ;
+- `docs/PROGRAM_NAMING.md` ;
+- `docs/PROGRAM_REGISTRY_CONTROL.md` ;
+- `registry/program_registry_seed.toml`.
+
+Le préfixe `program_` est interdit pour les surfaces canoniques. Les entrées dont la fonction est inconnue doivent rester en `unknown_*` avec un statut de classification, sans création de crate cible.
+
+Les programmes core Solana/SPL sont documentés séparément des DEX et routers, même s'ils restent dans le registre machine.