<!-- file: deltas/0.1.1/pre.001-fix.002.md -->
<!-- version: 1 -->

# Delta 0.1.1-pre.001-fix.002

## Base requise

Livraison précédente appliquée et commitée :

```text
0.1.1-pre.001-fix.001
```

## Type de livraison

```text
ksp-doc-0.1.1-pre.001-fix.002.zip
```

## Objectif

Compléter le cadrage Program IDs de `pre.001` avant ouverture de `pre.002`, après réaudit de l'ancien registre/IDLs bot3 et confrontation à des Program IDs publics actuels.

Ce correctif reste purement documentaire. Il fixe l'architecture de classification/recherche nécessaire pour que le registre KSP puisse ultérieurement retrouver les programmes par domaine, famille, protocole, sous-famille et génération sans dupliquer plusieurs registres statiques.

## Version Cargo

Aucun fichier de code/build/runtime n'est modifié.

`workspace.package.version` reste donc :

```text
0.1.1-pre.1
```

Identifiant de livraison/commit :

```text
0.1.1-pre.001-fix.002
```

## Fichiers ajoutés

- `deltas/0.1.1/pre.001-fix.002.md`

## Fichiers modifiés

- `docs/plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md` — version documentaire 2 -> 3.

## Décisions acquises

### Registre canonique unique

KSP ne doit pas maintenir des tableaux indépendants pour chaque vue (`native`, `amm`, protocole, etc.).

`entries()` reste la source canonique et les vues/recherches sont dérivées de la classification de chaque `ProgramIdEntry`.

### Taxonomie minimale

`ProgramIdEntry` doit être conçu pour porter au minimum les axes descriptifs suivants :

```text
domain
family
protocol
subfamily?
program_version?
kind
```

auxquels s'ajoutent le code KSP unique, la chaîne Base58 `PRGID_*` et le `Pubkey` `PRGIDPK_*`.

Les vocabulaires de classification restent extensibles. Core ne doit pas posséder une enum fermée de tous les protocoles/familles futurs.

### AMM comme famille agrégatrice

Le réaudit de bot3 montre que les anciens préfixes `AMM`, `CPMM`, `CLMM`, `DLMM`, `STABLE_SWAP` et `WEIGHTED_SWAP` représentent plusieurs spécialisations d'une même grande famille utile pour la recherche.

La direction KSP devient donc :

```text
family = amm
```

avec des `subfamily` optionnelles telles que :

```text
cpmm
clmm
dlmm
damm
stable_swap
weighted_swap
gamma
ssl
```

lorsqu'elles correspondent réellement à une branche/architecture reconnue.

Une future `amm_program_ids()` doit filtrer le registre canonique sur cette famille et inclure toutes ces sous-familles.

### `subfamily` et `program_version` sont deux axes indépendants

La version ne doit pas être détournée en sous-famille.

Cas audités :

- SPL Memo : trois Program IDs v1/v3/v4, même lignée fonctionnelle ;
- Aldrin AMM : v1/v2, même famille/protocole ;
- Meteora DAMM : sous-famille `damm`, versions v1/v2 ;
- Meteora DLMM : sous-famille `dlmm` distincte de DAMM ;
- Jupiter Aggregator : même lignée, versions v4/v6 ;
- GooseFX : GAMMA et SSL sont des branches distinctes ; `SSL v2` possède une version, tandis qu'aucun `v1` ne doit être inventé pour GAMMA.

### Nom du champ de version

Le champ retenu conceptuellement est :

```text
program_version
```

et non `protocol_version`.

Raison : un protocole peut posséder simultanément plusieurs programmes/composants dont les versions évoluent indépendamment. La version doit être attachée à la lignée du Program ID concerné, pas au protocole entier.

`program_version` est un label de génération reconnu (`v1`, `v2`, `v4`, `v6`, `v0.5`, etc.), pas nécessairement un SemVer.

### Version d'IDL explicitement distincte

Une version d'IDL/schema n'est pas une version de Program ID.

Exemples observés dans les IDLs archivées bot3 :

- Jupiter V6 : IDL `0.1.0` ;
- GooseFX SSL V2 : IDL `0.3.0` ;
- GooseFX GAMMA : IDL/schema `0.2.0` ;
- Meteora DAMM V2 : IDL/schema distinct de la génération publique `v2`.

La provenance/version des IDLs appartiendra à la couche Interface/decoder lorsqu'elle sera ouverte ; elle n'entre pas dans `ProgramIdEntry` de Core en `0.1.1`.

### Nomenclature des constantes

La nomenclature Rust est séparée de la taxonomie fonctionnelle.

Le premier segment après `PRGID_`/`PRGIDPK_` est désormais nommé `NAMESPACE`, afin de ne pas confondre le nom public stable avec le champ taxonomique `domain` :

```text
PRGID_<NAMESPACE>_<PROGRAM_OR_FAMILY>_<VARIANT?>_<VERSION?>
PRGIDPK_<NAMESPACE>_<PROGRAM_OR_FAMILY>_<VARIANT?>_<VERSION?>
```

Exemples :

```text
PRGID_SPL_MEMO_V3
PRGIDPK_SPL_MEMO_V3

PRGID_METEORA_DAMM_V2
PRGIDPK_METEORA_DAMM_V2

PRGID_GOOSEFX_GAMMA
PRGIDPK_GOOSEFX_GAMMA

PRGID_GOOSEFX_SSL_V2
PRGIDPK_GOOSEFX_SSL_V2
```

Le symbole public ne doit pas être renommé uniquement parce qu'une classification fonctionnelle est affinée plus tard.

### Recherches et vues prévues

Direction conceptuelle :

```text
ProgramIdEntry
ProgramIdFilter
entries()
program_ids(filter)
native_program_ids()
find_program_id()
```

Le filtre doit pouvoir combiner plusieurs critères.

Des helpers de recherche peuvent être proposés :

```text
program_ids_by_domain(...)
program_ids_by_family(...)
program_ids_by_protocol(...)
```

`native_program_ids()` reste une vue Core réelle de `0.1.1`.

`amm_program_ids()` est explicitement prévue pour la surface future possédant des IDs AMM, mais n'est pas créée vide pendant `0.1.1` puisque les AMM sont hors scope fonctionnel de la release.

Les vues doivent pouvoir être des iterators/views du registre canonique afin d'éviter la duplication de tableaux statiques.

## Réaudit effectué

### Archive bot3

Le réaudit a porté sur :

- `ks-program-ids` et ses 137 entrées historiques ;
- `ProgramIdEntry`, `entries()`, `native_program_ids()` et la recherche historique ;
- les familles historiques AMM/CLMM/CPMM/DLMM/router/orderbook/etc. ;
- les IDLs archivées, notamment GooseFX GAMMA/V2, Meteora DAMM/DLMM, Jupiter v4/v6, CCTP v1/v2, Raydium CLMM/CPMM, OpenBook v2 et Marginfi v2.

L'inventaire montre également qu'un même protocole traverse plusieurs familles : Jupiter, Raydium, Meteora, Kamino, MetaDAO, Pump, Metaplex, Orca, etc. `protocol` doit donc être un axe séparé de `family`.

### Sources externes actuelles

Contrôles représentatifs effectués le 2026-08-14 :

- Agave runtime `fetch-spl.sh` : Memo 1.0.0, 3.0.0 et 4.0.0 sont associés à trois Program IDs distincts ;
- `spl-memo-interface` actuel : modules `v1`, `v3`, `v4` distincts ;
- Solana Explorer et Solscan : présence/identification des Program IDs Memo et de programmes DEX audités ;
- GooseFX officiel : GAMMA est une lignée AMM distincte ; l'écosystème publie également la lignée SSL ;
- Meteora officiel : DAMM v1, DAMM v2 et DLMM sont des surfaces distinctes ;
- Jupiter officiel : plusieurs générations du Swap Aggregator sont distinguées par Program ID.

Ces contrôles sont utilisés comme validation de taxonomie, pas comme dépendances KSP.

## Impact sur `pre.003`

`pre.003` devra désormais :

- implémenter `ProgramIdEntry` avec une taxonomie compatible avec les axes acquis ;
- implémenter `ProgramIdFilter` ou une forme équivalente permettant les intersections ;
- dériver `native_program_ids()` du registre canonique ;
- tester les filtres par domaine/famille/protocole/sous-famille/version/kind ;
- ne jamais confondre génération du programme et version d'IDL ;
- préserver la possibilité d'ajouter plus tard `amm_program_ids()` sans modifier la structure fondamentale du registre.

## Hors scope inchangé

Ce correctif n'ajoute aucun Program ID SPL/DEX au code de `0.1.1` et n'ouvre toujours pas :

- Logging ;
- Config ;
- Tauri ;
- Wallet/signing ;
- codecs wire ;
- Interface/IDL runtime ;
- Program decoding/dispatch ;
- execution ;
- Transport ;
- Store ;
- Materializer ;
- workers/jobs/pipelines ;
- scenarios ;
- trading/ML.

## Validations exécutées

- réaudit du registre `ks-program-ids` de l'archive bot3 ;
- inventaire des Program IDs versionnés et des protocoles présents dans plusieurs familles ;
- inspection ciblée des IDLs multi-version/à plusieurs sous-familles ;
- confrontation représentative avec Agave/SPL, Solana Explorer, Solscan, GooseFX, Meteora et Jupiter ;
- relecture du plan après modification ;
- contrôle statique des headers/version documentaire ;
- contrôle des fins de fichiers ;
- contrôle de l'absence de modification Cargo/code/runtime dans ce fix.

## Validations non exécutées

Aucune validation Cargo n'est requise pour ce fix exclusivement documentaire et aucune n'est déclarée réussie.

## Suite

Après application et commit de ce correctif, le cadrage `pre.001` peut être considéré comme clôturé et la session peut passer à :

```text
0.1.1-pre.002 — Error/Result et fondation API
```