Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.0.3-pre.004

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-14 09:51:30 +02:00
parent 544e0351b8
commit d33911f925
12 changed files with 776 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Cargo.toml
View File

@@ -1,12 +1,12 @@
# file: Cargo.toml # file: Cargo.toml
# version: 9 # version: 10
[workspace] [workspace]
resolver = "3" resolver = "3"
members = ["crates/ksp-core-lib"] members = ["crates/ksp-core-lib"]
[workspace.package] [workspace.package]
version = "0.0.3-pre.3" version = "0.0.3-pre.4"
edition = "2024" edition = "2024"
license = "MIT" license = "MIT"
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"

189
deltas/0.0.3/pre.004.md Normal file
View File

@@ -0,0 +1,189 @@
<!-- file: deltas/0.0.3/pre.004.md -->
<!-- version: 1 -->
# Delta 0.0.3-pre.004
## Base requise
`v0.0.3-pre.003`.
## Objectif
Détailler la frontière Wire/Program sans ouvrir encore la totalité de l'orchestration Execution/Policy.
La tranche formalise :
- `ksp-interface-lib` et la propriété des codecs wire ;
- la politique de sélection/réimplémentation des crates d'interface externes ;
- `ksp-program-api` ouvert/extensible ;
- les familles de decoders ;
- `ProgramExecutionPreparer` ;
- le lifecycle machine-readable des opérations anciennes/abandonnées ;
- le registry officiel + externe ;
- l'organisation future de `ksp-program-lib` ;
- le workflow d'une extension Program développée indépendamment.
## Version Cargo
`workspace.package.version` passe de :
```text
0.0.3-pre.3
```
à :
```text
0.0.3-pre.4
```
Le header de `Cargo.toml` passe de version 9 à 10.
## Fichiers ajoutés
- `docs/architecture/006-WIRE_AND_PROGRAM.md`
- `deltas/0.0.3/pre.004.md`
## Fichiers modifiés
- `Cargo.toml`
- `docs/architecture/000-README.md`
- `docs/architecture/003-COMPONENT_CONTRACTS.md`
- `docs/architecture/004-COMPONENT_INVENTORY.md`
- `docs/architecture/005-DEPENDENCY_GRAPH.md`
- `docs/rules/RULES_DEPENDENCIES.md`
- `docs/rules/RULES_KSP.md`
- `docs/IDEAS.md`
- `docs/plans/001-V0_0_3_PLAN.md`
- `prompts/001-V0_1_X_START_PROMPT.md`
## Fichiers supprimés
Aucun.
## Décisions principales
### Codecs wire
`ksp-interface-lib` est le propriétaire normal des dépendances wire telles que `borsh`, `wincode` et équivalents pour les interfaces officielles KSP.
`ksp-program-lib` ne redécode pas directement une surface officielle avec une autre génération de codec.
### Sélection des interfaces externes
Une interface externe est retenue selon :
- caractère officiel/normatif ;
- stabilité/utilité de l'API ;
- compatibilité avec le stack actuel ;
- absence de dette de générations anciennes évitable.
Une crate protocolaire qui impose une ancienne génération incompatible d'un codec fondamental peut être remplacée par une réimplémentation KSP bornée aux contrats wire nécessaires.
Le workspace devra auditer les doublons de dépendances fondamentales (`cargo tree -d`, `cargo tree -i ...`) lorsque les dépendances fonctionnelles seront introduites.
### Program API ouverte
Aucun enum central fermé de Program IDs n'est prévu.
Le résultat décodé doit pouvoir être auto-identifié, extensible et persistable.
`Any` ne peut pas constituer à lui seul le contrat de résultat.
### Decoders
Les capacités sont séparables, avec notamment :
```text
ProgramInstructionDecoder
ProgramAccountDecoder
```
et ajout de surfaces Event/ReturnData seulement lorsqu'un besoin réel le justifie.
### Préparation d'exécution
Le terme `ProgramExecutor` est remplacé conceptuellement par :
```text
ProgramExecutionPreparer
```
Il prépare l'opération protocolaire mais ne signe, simule, envoie ou confirme pas la transaction.
### Lifecycle / deprecated
Le statut d'une opération est machine-readable.
Une opération simplement ancienne n'est pas automatiquement deprecated.
Une opération réellement abandonnée peut rester techniquement préparée avec warning et être ensuite autorisée/refusée par la policy supérieure.
`#[deprecated]` n'est pas obligatoire.
Le decoder continue de décoder les surfaces historiques distinguables.
### Registry et extensions
Le registry doit composer implémentations officielles, externes et expérimentales.
Une extension s'appelle conceptuellement :
```text
ksp-program-<name>-lib
```
et implémente `ksp-program-api`.
Elle peut exister/tester indépendamment de `ksp-program-lib`.
Si son interface wire n'est pas encore officiellement intégrée à KSP, elle peut temporairement posséder ses propres définitions compatibles.
Lors de l'intégration officielle, le wire migre vers `ksp-interface-lib` et l'implémentation Program vers `ksp-program-lib` sans modifier le contrat commun uniquement pour ce nouveau Program ID.
### Organisation de `ksp-program-lib`
Principe retenu :
```text
domain -> program/protocol -> capability
```
avec une direction de travail de type :
```text
<domain>/<program>/dec/*
<domain>/<program>/exec_prep/*
```
Les noms exacts de répertoires restent à valider avec la première implémentation.
## Plan ajusté
La tranche Execution/Policy est déplacée vers `pre.005`.
Les tranches suivantes sont décalées :
- `pre.005` — Execution/Policy ;
- `pre.006` — Data/Store/Acquisition ;
- `pre.007` — Apps/Workers/Jobs/Scenarios ;
- `pre.008` — plan des premières releases fonctionnelles ;
- `pre.009` — clôture fondatrice.
## Questions reportées
- représentation exacte du payload décodé ouvert/persistable ;
- descripteurs/registry exacts ;
- conflits entre plusieurs implémentations d'un même Program ID ;
- formes Rust exactes des traits ;
- noms définitifs `dec` / `exec_prep`.
Ces points seront fixés avec les premières implémentations lorsqu'un cas réel permet de tester la qualité du contrat.
## Validations
- headers `file:` / `version:` vérifiés ;
- `Cargo.toml` parsé et version `0.0.3-pre.4` vérifiée ;
- liens vers `006-WIRE_AND_PROGRAM.md` vérifiés ;
- plan `pre.005` à `pre.009` vérifié ;
- aucune commande Cargo de build/test exécutée : ce delta reste documentaire et n'ajoute aucun code Rust fonctionnel.

34
docs/IDEAS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/IDEAS.md --> <!-- file: docs/IDEAS.md -->
<!-- version: 7 --> <!-- version: 8 -->
# Idées à explorer # Idées à explorer
@@ -160,3 +160,35 @@ Ne pas créer de `ksp-pipeline-lib`. Les pipelines sont introduits séparément
**Status :** Retenue **Status :** Retenue
Construire d'abord statistiques, features, signaux, risque, backtests, détection de patterns/anomalies et intégrations ML telles que XGBoost. La couche/application de trading opérationnelle est construite ensuite. Construire d'abord statistiques, features, signaux, risque, backtests, détection de patterns/anomalies et intégrations ML telles que XGBoost. La couche/application de trading opérationnelle est construite ensuite.
## Program API — questions d'implémentation
### Payload décodé ouvert et persistable
**Status :** À explorer lors de la première implémentation
`ksp-program-api` ne doit utiliser ni enum central fermé de Program IDs ni `Any` comme seule représentation.
À décider à partir des besoins réels :
- value tree typé KSP ;
- schema/version + payload binaire ;
- structure sérialisable ouverte ;
- autre contrat garantissant identification, persistence et extensibilité.
### Conflits de registry
**Status :** À explorer
Définir la politique lorsqu'un registry reçoit plusieurs implémentations capables de traiter le même Program ID/surface/version :
- priorité explicite ;
- refus du conflit ;
- sélection par version/capability ;
- autre mécanisme documenté.
### Convention interne `dec` / `exec_prep`
**Status :** À explorer avec les premiers modules
Le principe `domain/program/capability` est retenu. Les noms exacts des dossiers courts (`dec`, `exec_prep`) seront validés avec la première vraie arborescence.

5
docs/architecture/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/000-README.md --> <!-- file: docs/architecture/000-README.md -->
<!-- version: 4 --> <!-- version: 5 -->
# Architecture KSP # Architecture KSP
@@ -21,6 +21,7 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
2. [`002-LAYERS_AND_DEPENDENCIES.md`](002-LAYERS_AND_DEPENDENCIES.md) — couches conceptuelles, sens des dépendances et responsabilités des exécutables ; 2. [`002-LAYERS_AND_DEPENDENCIES.md`](002-LAYERS_AND_DEPENDENCIES.md) — couches conceptuelles, sens des dépendances et responsabilités des exécutables ;
3. [`003-COMPONENT_CONTRACTS.md`](003-COMPONENT_CONTRACTS.md) — frontières initiales des composants structurants et contrats déjà acquis ; 3. [`003-COMPONENT_CONTRACTS.md`](003-COMPONENT_CONTRACTS.md) — frontières initiales des composants structurants et contrats déjà acquis ;
4. [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) — inventaire courant des domaines, APIs, bibliothèques, workers, jobs, scénarios et applications candidates ; 4. [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) — inventaire courant des domaines, APIs, bibliothèques, workers, jobs, scénarios et applications candidates ;
5. [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) — graphe de dépendances retenu, dépendances interdites et frontières de conversion/composition. 5. [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) — graphe de dépendances retenu, dépendances interdites et frontières de conversion/composition ;
6. [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) — propriété des contrats wire, politique de dépendances codecs/interfaces, API Program ouverte, preparation d'exécution et extensibilité externe.
`004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires. `004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires.

4
docs/architecture/003-COMPONENT_CONTRACTS.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md --> <!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
<!-- version: 5 --> <!-- version: 6 -->
# Contrats initiaux des composants KSP # Contrats initiaux des composants KSP
@@ -9,7 +9,7 @@ Ce document enregistre les frontières déjà suffisamment claires pour guider l
Le principe commun est de définir tôt les contrats nécessaires entre composants, puis d'enrichir les implémentations lorsque le besoin réel apparaît. Le principe commun est de définir tôt les contrats nécessaires entre composants, puis d'enrichir les implémentations lorsque le besoin réel apparaît.
L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) et le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md). L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) et les contrats Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md).
## Convention API / implémentation ## Convention API / implémentation

73
docs/architecture/004-COMPONENT_INVENTORY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md --> <!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
<!-- version: 2 --> <!-- version: 3 -->
# Inventaire initial des composants KSP # Inventaire initial des composants KSP
@@ -9,7 +9,7 @@ Ce document constitue le premier inventaire architectural de `0.0.3-pre.002`.
Il répond principalement à la question : **quel composant possède quelle responsabilité ?** Il répond principalement à la question : **quel composant possède quelle responsabilité ?**
Le premier inventaire a été produit en `0.0.3-pre.002`. `0.0.3-pre.003` l'a corrigé à partir du graphe formalisé dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md). Les détails internes des APIs restent toutefois révisables dans les prereleases spécialisées suivantes. Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé à partir du graphe, puis `pre.004` a détaillé Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md). Les détails de types Rust restent révisables avec les premières implémentations.
## Statuts ## Statuts
@@ -21,40 +21,41 @@ Le premier inventaire a été produit en `0.0.3-pre.002`. `0.0.3-pre.003` l'a co
## Inventaire synthétique ## Inventaire synthétique
| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale | | Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale |
|-------------------------|---------------------------------------------|---------------|-------------------|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| |-------------------------|---------------------------------------------|-------------------------|-------------------|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux | | Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées | | Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées |
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | logging/tracing commun | | Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | logging/tracing commun |
| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles | | Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles |
| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics decoder/executor et types associés | | Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics ouverts de décodage, préparation d'exécution, descriptors et registry |
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés | | Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders et `ProgramExecutionPreparer` officiels organisés par domaine/programme/capacité |
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | `0.2.x+` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution | | Program extension | `ksp-program-<name>-lib` | lib externe/optionnelle | N2 | À la demande | dès besoin | implémentation externe de `ksp-program-api` pour un Program ID non encore intégré officiellement |
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | orchestration spécialisée entre opération préparée, policy, wallet et transport ; dépend de `ksp-program-api`, pas de `ksp-program-lib` | | Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | `0.2.x+` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution |
| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store | | Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | orchestration spécialisée entre opération préparée, policy, wallet et transport ; dépend de `ksp-program-api`, pas de `ksp-program-lib` |
| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain | | Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store |
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature | | Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain |
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation | | Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP | | Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
| Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées | | Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries | | Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées |
| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus | | Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries |
| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur | | Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus |
| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data | | Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur |
| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique | | Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data |
| Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core | | Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique |
| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine | | Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core |
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables | | Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine |
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise | | Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques | | Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine | | Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant | | Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante | | Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant |
| Specialized pipelines | `ksp-pipeline-<role>-lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale | | Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML | | Specialized pipelines | `ksp-pipeline-<role>-lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale |
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte | | Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana | | Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX | | Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana |
| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX |
## APIs séparées retenues ## APIs séparées retenues

39
docs/architecture/005-DEPENDENCY_GRAPH.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md --> <!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
<!-- version: 1 --> <!-- version: 2 -->
# Graphe de dépendances KSP # Graphe de dépendances KSP
@@ -87,6 +87,23 @@ ksp-interface-lib -> ksp-core-lib
--- ---
# Propriété des codecs wire
Pour les surfaces wire officielles KSP :
```text
ksp-interface-lib
-> codecs wire nécessaires (borsh/wincode/...)
```
`ksp-program-lib` n'ajoute pas directement une autre génération de codec pour les mêmes surfaces.
Une extension Program externe peut temporairement posséder son wire lorsqu'il n'est pas encore officiellement intégré à `ksp-interface-lib`.
Le critère d'adoption d'une crate d'interface externe inclut la compatibilité de son graphe de dépendances avec le stack KSP actuel.
---
# Graphe Program # Graphe Program
```text ```text
@@ -102,7 +119,7 @@ ksp-program-lib
## Frontière de `ksp-program-api` ## Frontière de `ksp-program-api`
`ksp-program-api` doit porter les contrats publics nécessaires à une implémentation externe de decoder/executor. `ksp-program-api` doit porter les contrats publics nécessaires à une implémentation externe de decoder/execution preparation.
Il est également le propriétaire candidat du **contrat d'opération préparée** produit par la sémantique programme et consommé par la couche d'exécution. Il est également le propriétaire candidat du **contrat d'opération préparée** produit par la sémantique programme et consommé par la couche d'exécution.
@@ -131,10 +148,26 @@ ksp-program-lib -X-> ksp-materializer-lib
ksp-program-lib -X-> ksp-execution-lib ksp-program-lib -X-> ksp-execution-lib
``` ```
Le decoder/executor de programme reste donc testable sans réseau, wallet ou base de données. Le decoder/execution preparation de programme reste donc testable sans réseau, wallet ou base de données.
--- ---
## Implémentations Program externes
Une implémentation externe peut dépendre de :
```text
ksp-program-<name>-lib
-> ksp-program-api
-> ksp-core-lib
-> ksp-interface-lib # lorsque le wire officiel nécessaire existe
```
Elle ne dépend pas obligatoirement de `ksp-program-lib`.
Le runtime peut composer registry officiel + registry/implémentations externes derrière `ksp-program-api`.
# Graphe Execution / Policy # Graphe Execution / Policy
`ksp-execution-policy-api` et `ksp-execution-lib` sont retenus comme composants. `ksp-execution-policy-api` et `ksp-execution-lib` sont retenus comme composants.

418
docs/architecture/006-WIRE_AND_PROGRAM.md Normal file
View File

@@ -0,0 +1,418 @@
<!-- file: docs/architecture/006-WIRE_AND_PROGRAM.md -->
<!-- version: 1 -->
# Wire, Program API et implémentations Program
## Objet
Ce document constitue la sortie principale de `0.0.3-pre.004`.
Il précise :
- le rôle de `ksp-interface-lib` ;
- la propriété des codecs wire ;
- la politique de sélection/réimplémentation des crates d'interface externes ;
- la forme générale et ouverte de `ksp-program-api` ;
- la séparation decoder / préparation d'exécution ;
- le registry extensible ;
- l'organisation interne prévue de `ksp-program-lib` ;
- le workflow d'une implémentation de programme développée hors de l'implémentation officielle.
Les types Rust exacts restent volontairement à définir lors de la première implémentation réelle.
## `ksp-interface-lib`
`ksp-interface-lib` est la façade wire officielle KSP pour les programmes Solana supportés officiellement.
Elle possède ou réexporte de manière contrôlée les contrats nécessaires tels que :
- discriminants ;
- layouts d'instructions ;
- layouts de comptes ;
- enums/structures wire ;
- sérialisation/désérialisation wire ;
- règles et seeds de PDA lorsque ces règles appartiennent au contrat protocolaire ;
- constructeurs d'instructions lorsque ceux-ci représentent directement le contrat wire.
Les Program IDs fondamentaux restent possédés par `ksp-core-lib`.
`ksp-interface-lib` ne possède pas :
- RPC/WS/provider ;
- wallet/signature ;
- persistence ;
- matérialisation ;
- interprétation canonique/métier d'une instruction ;
- policy/safety ;
- lifecycle d'exécution réseau.
## Propriété des codecs wire
Pour le code KSP officiel, les dépendances directement utilisées pour encoder/décoder les formats wire, notamment `borsh`, `wincode` ou codecs équivalents, appartiennent normalement à `ksp-interface-lib`.
La règle n'interdit pas qu'une autre crate KSP utilise un codec pour une raison indépendante du wire Solana, mais une telle dépendance directe doit avoir une justification distincte.
En particulier :
```text
ksp-interface-lib
-> borsh / wincode / codecs wire nécessaires
ksp-program-lib
-X-> borsh / wincode pour redécoder directement le wire protocolaire
```
`ksp-program-lib` reçoit des contrats typés/wire exposés par la façade officielle au lieu de recréer la sérialisation protocolaire.
## Politique de sélection des interfaces externes
Une crate externe d'interface Solana/Anza peut être utilisée directement lorsque :
1. elle appartient à une source officielle ou suffisamment normative pour le contrat concerné ;
2. sa surface est suffisamment stable et finale pour l'usage KSP ;
3. son graphe de dépendances est compatible avec le stack de dépendances KSP actuel ;
4. elle n'introduit pas sans nécessité une génération ancienne/incompatible d'un codec ou d'une primitive fondamentale ;
5. son usage évite une réimplémentation KSP sans réduire le contrôle du contrat public.
Une crate protocolaire externe peut être rejetée même si son API fonctionne lorsqu'elle impose un stack ancien ou incompatible avec le reste du workspace.
### Exemples observés pendant la planification
`solana-loader-v3-interface` illustre une interface officielle actuelle qui peut raisonnablement être conservée plutôt que réécrite lorsque sa version et son graphe restent compatibles avec KSP.
`mpl-token-metadata` illustre le cas inverse : KSP ne prévoit pas de l'intégrer comme dépendance runtime. Les contrats wire Metaplex Token Metadata nécessaires seront réimplémentés/possédés par `ksp-interface-lib`.
Ces exemples sont des applications de la règle, pas des exceptions codées en dur : l'état des dépendances doit être revérifié au moment de chaque implémentation.
## Politique anti-doublons de générations
KSP ne cherche pas à figer arbitrairement une version précise des dépendances. Le projet cherche au contraire à rester sur des générations récentes et compatibles.
Les doublons de versions/générations de dépendances fondamentales doivent être inspectés régulièrement, notamment pour :
- codecs wire ;
- primitives Solana ;
- sérialisation ;
- bibliothèques cryptographiques fondamentales.
Un doublon réellement imposé et inévitable par une dépendance retenue peut être temporairement accepté avec justification.
Un doublon évitable provoqué par une crate protocolaire remplaçable doit être éliminé plutôt que normalisé comme dette permanente.
Outils d'audit attendus lorsque le workspace fonctionnel le permettra :
```bash
cargo tree -d
cargo tree -i borsh
cargo tree -i wincode
```
La liste sera complétée selon les dépendances réellement utilisées.
## `ksp-program-api`
`ksp-program-api` porte des contrats publics **ouverts**.
Une implémentation externe doit pouvoir prendre en charge un Program ID encore inconnu de `ksp-program-lib` sans modifier une enum centrale KSP.
### Pas d'enum fermée de programmes
Une structure de la forme suivante est explicitement évitée :
```text
enum DecodedProgram {
Token(...),
Token2022(...),
Meteora(...),
...
}
```
car chaque nouveau protocole exigerait une modification de l'API centrale.
De même, un `Any` runtime non persistable ne peut pas constituer l'unique représentation d'un résultat décodé.
Le résultat doit rester :
- auto-identifiable ;
- extensible ;
- sérialisable/persistable lorsque la frontière Core l'exige ;
- exploitable par une implémentation externe de materializer ;
- compatible avec l'ajout de Program IDs sans modification de l'API commune.
La représentation exacte du payload ouvert sera définie avec les contrats Core/Store/Materializer réels, sans introduire prématurément une enum fermée.
## Familles de decoders
Plutôt qu'un unique trait possédant toutes les surfaces possibles, `ksp-program-api` doit pouvoir distinguer les capacités de décodage.
Familles initiales candidates :
```text
ProgramInstructionDecoder
ProgramAccountDecoder
ProgramEventDecoder
ProgramReturnDataDecoder
```
Les deux premières sont considérées comme besoins fondamentaux probables.
Les autres ne sont ajoutées que lorsqu'une première surface réelle le justifie.
Une implémentation de programme n'est pas obligée de fournir toutes les capacités.
Des descripteurs communs doivent permettre d'identifier les capacités effectivement supportées.
## Politique de décodage historique
Le decoder vise toute surface techniquement décodable dont la définition est connue :
- actuelle ;
- ancienne ;
- legacy ;
- abandonnée ;
- expérimentale/test lorsque le wire est connu ;
- historique distinguable.
Le statut de lifecycle d'une opération n'empêche jamais son décodage historique.
Si une définition a réellement été écrasée sous une identité indistinguable et que l'ancienne forme ne peut plus être reconnue de manière fiable, la définition applicable la plus récente est utilisée.
Le concept `deprecated` n'est donc pas un filtre de decoder.
## Préparation d'exécution Program
Le terme `ProgramExecutor` est abandonné dans le cadrage KSP parce qu'il suggère une exécution transactionnelle complète.
Le contrat prévu est nommé conceptuellement :
```text
ProgramExecutionPreparer
```
Sa responsabilité :
```text
ProgramExecutionRequest
|
v
ProgramExecutionPreparer
|
v
PreparedProgramExecution
```
Noms exacts des types à confirmer lors de l'implémentation.
Le preparer peut notamment :
- valider les paramètres protocolaires ;
- déterminer les comptes requis ;
- dériver les PDA nécessaires ;
- construire une ou plusieurs instructions ;
- indiquer les autorités/signers requis ;
- exposer les contraintes techniques propres à l'opération.
Il ne réalise pas :
- sélection du wallet réel ;
- accès aux secrets ;
- récupération du recent blockhash ;
- signature transactionnelle ;
- simulation RPC ;
- envoi réseau ;
- confirmation ;
- retry réseau ;
- policy/safety de produit.
Ces responsabilités appartiennent aux couches d'exécution supérieures.
## `PreparedProgramExecution`
Le contrat préparé entre Program et Execution doit pouvoir transporter conceptuellement :
- identité du programme/opération ;
- instructions ;
- comptes/authorities/signers requis ;
- contraintes techniques ;
- informations nécessaires à une policy supérieure ;
- metadata de préparation utiles à l'exécution.
Il ne contient pas de secret wallet et ne fixe pas un endpoint réseau concret.
Il doit être consommable par `ksp-execution-lib` indépendamment du fait que l'implémentation Program provienne de `ksp-program-lib` ou d'une crate externe.
## Lifecycle des opérations préparables
Le lifecycle d'une opération d'exécution doit être machine-readable.
Il faut distinguer au minimum conceptuellement :
- opération actuelle/supportée ;
- opération legacy/ancienne mais pas nécessairement déconseillée ;
- opération réellement abandonnée/déconseillée.
Les noms exacts des statuts seront définis plus tard.
Le statut « deprecated » est réservé à une surface clairement abandonnée/remplacée, pas simplement ancienne.
KSP ne rend pas obligatoire l'annotation Rust `#[deprecated]`.
Une opération techniquement encore préparée mais marquée comme abandonnée peut :
1. produire un warning explicite ;
2. transmettre son statut à `ksp-execution-policy-api` ;
3. être autorisée ou rejetée par la policy supérieure selon le contexte.
Le decoder continue de la reconnaître indépendamment de ce statut.
## Registry extensible
Le registry Program doit pouvoir combiner :
- implémentations officielles KSP ;
- implémentations externes ;
- implémentations expérimentales.
Les descripteurs doivent permettre d'identifier au minimum conceptuellement :
- Program ID ;
- identité/version de l'implémentation ;
- capacités de décodage ;
- opérations préparables ;
- statut/lifecycle des opérations ;
- autres capacités nécessaires au dispatch.
Le contrat exact du registry sera défini lors de l'implémentation.
Le registry ne doit pas nécessiter une modification de `ksp-program-api` pour enregistrer un nouveau Program ID.
## Implémentations externes
Une extension externe de programme est une **implémentation** de `ksp-program-api`, pas une nouvelle API commune.
Nomenclature recommandée lorsque l'extension suit les conventions KSP :
```text
ksp-program-<name>-lib
```
Exemple conceptuel :
```text
ksp-program-fluxbeam-lib
```
et non :
```text
ksp-program-fluxbeam-api
```
Cette crate peut dépendre de :
```text
ksp-program-api
ksp-core-lib
ksp-interface-lib
```
selon les besoins.
Elle peut être développée, testée et utilisée par un runtime KSP sans être intégrée à `ksp-program-lib`.
## Wire d'une extension encore non officielle
`ksp-interface-lib` est la façade wire **officielle KSP**, mais `ksp-program-api` ne doit pas empêcher une extension externe de fournir temporairement ses propres définitions wire.
Deux cas sont possibles :
```text
interface officielle déjà dans KSP
-> extension utilise ksp-interface-lib
interface pas encore intégrée
-> extension possède sa définition wire compatible
-> extension implémente ksp-program-api
```
Lors de l'intégration officielle :
1. les définitions wire sont revues/vérifiées ;
2. les contrats wire nécessaires migrent vers `ksp-interface-lib` ;
3. decoder/preparer migrent vers `ksp-program-lib` ;
4. le contrat `ksp-program-api` ne change pas pour cette seule raison.
## Organisation interne de `ksp-program-lib`
`ksp-program-lib` doit être organisé d'abord par domaine puis par programme/protocole, et seulement ensuite par capacité.
Direction retenue :
```text
<domain>/
<program-or-protocol>/
dec/
...
exec_prep/
...
```
Exemples conceptuels :
```text
spl/
token_2022/
dec/
exec_prep/
metadata/
token/
mpl/
dec/
exec_prep/
dex/
meteora/
dlmm/
dec/
exec_prep/
```
Les noms courts `dec` / `exec_prep` restent une convention candidate ; les noms précis seront décidés avec les premières vraies arborescences Rust.
Le principe durable est :
```text
domain -> program/protocol -> capability
```
et non un répertoire racine géant `decoder/` ou `executor/` contenant tous les protocoles.
## Conformité wire
Pour chaque contrat wire réimplémenté, la documentation/tests doivent permettre d'identifier la source normative utilisée.
Les validations peuvent combiner selon le cas :
- documentation/source officielle ;
- fixtures officielles ;
- transactions/comptes réels connus ;
- golden vectors ;
- comparaison avec une implémentation de référence lorsqu'elle peut être utilisée sans polluer durablement le graphe KSP.
Une crate externe provoquant volontairement une génération incompatible de dépendances fondamentales ne doit pas être ajoutée au workspace simplement pour faciliter un test si des fixtures/vecteurs indépendants permettent la même vérification.
## Questions laissées ouvertes
La première implémentation Program devra encore fixer précisément :
- formes Rust des traits decoder ;
- représentation du payload décodé ouvert/persistable ;
- forme exacte des descriptors ;
- types exacts `ProgramExecutionRequest` / `PreparedProgramExecution` ;
- forme du registry et règles de conflit entre plusieurs implémentations d'un même Program ID ;
- stratégie précise de warning/log pour opérations abandonnées ;
- convention finale `dec` / `exec_prep`.
La tranche suivante doit traiter `ksp-execution-policy-api` et `ksp-execution-lib` sans rouvrir les responsabilités Program définies ici.

44
docs/plans/001-V0_0_3_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/001-V0_0_3_PLAN.md --> <!-- file: docs/plans/001-V0_0_3_PLAN.md -->
<!-- version: 7 --> <!-- version: 8 -->
# Plan KSP 0.0.3 # Plan KSP 0.0.3
@@ -13,7 +13,7 @@ Transformer le brainstorming KSP en architecture, règles, inventaire et plan su
- `pre.002` — inventaire initial des composants ; - `pre.002` — inventaire initial des composants ;
- `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition. - `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition.
La prochaine tranche prévue est `pre.004`, consacrée à Program/Wire/Execution. La tranche `pre.004` est consacrée à Wire/Program. Execution/Policy est volontairement déplacé vers `pre.005` afin de garder des prereleases de planification bornées.
## Décisions structurantes actuelles ## Décisions structurantes actuelles
@@ -51,20 +51,32 @@ Livré :
- correction de `004-COMPONENT_INVENTORY.md` ; - correction de `004-COMPONENT_INVENTORY.md` ;
- suppression des décisions négatives présentées à tort comme tâches du roadmap. - suppression des décisions négatives présentées à tort comme tâches du roadmap.
### `pre.004` — Programmes, wire et exécution ### `pre.004` — Wire et Program
Objectifs prévus : Livré :
- détailler `ksp-interface-lib` ; - propriété et rôle de `ksp-interface-lib` ;
- détailler `ksp-program-api` et `ksp-program-lib` ; - propriété des codecs wire ;
- définir précisément decoder API et executor API ; - politique anti-doublons de générations et sélection/réimplémentation des interfaces externes ;
- définir le contrat d'opération préparée ; - API Program ouverte ;
- définir `ksp-execution-policy-api` ; - familles de decoders par capacité ;
- détailler le cycle de `ksp-execution-lib` : préparation, policy, simulation, signature, envoi, confirmation ; - `ProgramExecutionPreparer` à la place d'un executor transactionnel ambigu ;
- cadrer conformité wire, historique/deprecated et policy supérieure ; - statut lifecycle machine-readable pour les opérations anciennes/abandonnées ;
- vérifier que la tranche reste dans le budget de complexité, sinon la scinder. - registry extensible official + external ;
- organisation `domain -> program/protocol -> capability` ;
- workflow d'une implémentation externe avant intégration officielle.
### `pre.005` — Données, store et acquisitions ### `pre.005` — Execution et Policy
- détailler `ksp-execution-policy-api` ;
- détailler `ksp-execution-lib` ;
- consommer `PreparedProgramExecution` sans dépendre de `ksp-program-lib` ;
- définir les étapes policy, simulation, wallet/signature, transport/envoi, confirmation ;
- déterminer les policies de scenario Devnet vs produit général ;
- traiter erreurs/retry/confirmation et limites de responsabilité ;
- scinder à nouveau si la tranche devient trop dense.
### `pre.006` — Données, store et acquisitions
- détailler `ksp-materializer-api` / `ksp-materializer-lib` ; - détailler `ksp-materializer-api` / `ksp-materializer-lib` ;
- détailler `ksp-store-api` / `ksp-store-lib` ; - détailler `ksp-store-api` / `ksp-store-lib` ;
@@ -74,7 +86,7 @@ Objectifs prévus :
- cadrer les workers de processing ; - cadrer les workers de processing ;
- revisiter niveaux durables, replay, provenance et idempotence. - revisiter niveaux durables, replay, provenance et idempotence.
### `pre.006` — Applications, workers, jobs, scenarios et pipelines spécialisés ### `pre.007` — Applications, workers, jobs, scenarios et pipelines spécialisés
- formaliser les apps spécialisées ; - formaliser les apps spécialisées ;
- détailler `ksp-worker-control-lib` ; - détailler `ksp-worker-control-lib` ;
@@ -83,14 +95,14 @@ Objectifs prévus :
- cadrer l'orchestrateur futur ; - cadrer l'orchestrateur futur ;
- inventorier les pipelines spécialisés réellement nécessaires. - inventorier les pipelines spécialisés réellement nécessaires.
### `pre.007` — Plan des premières releases fonctionnelles ### `pre.008` — Plan des premières releases fonctionnelles
- transformer les séries `0.1.x+` en premières releases concrètes ; - transformer les séries `0.1.x+` en premières releases concrètes ;
- dimensionner chaque release concrète ; - dimensionner chaque release concrète ;
- choisir la première release `0.1.N` ; - choisir la première release `0.1.N` ;
- transformer le brouillon de prompt en prompt quasi-final de cette release concrète. - transformer le brouillon de prompt en prompt quasi-final de cette release concrète.
### `pre.008` — Clôture fondatrice ### `pre.009` — Clôture fondatrice
- validations finales de cohérence ; - validations finales de cohérence ;
- documentation/nettoyage/archivage ; - documentation/nettoyage/archivage ;

13
docs/rules/RULES_DEPENDENCIES.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/RULES_DEPENDENCIES.md --> <!-- file: docs/rules/RULES_DEPENDENCIES.md -->
<!-- version: 2 --> <!-- version: 3 -->
# Règles des dépendances KSP # Règles des dépendances KSP
@@ -23,11 +23,22 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
- **DEP-KSP-004** — Aucun `ksp-data-api` global n'est introduit uniquement pour éviter des conversions explicites entre modèles appartenant à des responsabilités différentes. - **DEP-KSP-004** — Aucun `ksp-data-api` global n'est introduit uniquement pour éviter des conversions explicites entre modèles appartenant à des responsabilités différentes.
- **DEP-KSP-005** — Une dépendance autorisée par le graphe n'est ajoutée au manifeste que lorsqu'un usage réel la justifie. - **DEP-KSP-005** — Une dépendance autorisée par le graphe n'est ajoutée au manifeste que lorsqu'un usage réel la justifie.
## Codecs wire et cohérence des versions
- **DEP-WIRE-001** — Pour les surfaces wire officielles KSP, les dépendances directes vers `borsh`, `wincode` ou codecs équivalents appartiennent normalement à `ksp-interface-lib`.
- **DEP-WIRE-002** — `ksp-program-lib` ne redécode pas directement une surface possédée par `ksp-interface-lib` avec sa propre dépendance codec.
- **DEP-WIRE-003** — Une crate d'interface externe est retenue seulement si sa source/API et son graphe de dépendances sont suffisamment compatibles avec le stack KSP actuel.
- **DEP-WIRE-004** — Une crate protocolaire externe qui impose une génération ancienne/incompatible d'une dépendance fondamentale peut être remplacée par une réimplémentation KSP bornée aux contrats wire nécessaires.
- **DEP-WIRE-005** — Les doublons de générations de dépendances fondamentales sont audités et les doublons évitables doivent être éliminés ; un doublon inévitable requiert une justification.
- **DEP-WIRE-006** — KSP cherche des versions récentes compatibles et ne fixe pas arbitrairement une ancienne version uniquement pour conserver une crate protocolaire remplaçable.
- **DEP-WIRE-007** — Une extension Program externe peut posséder temporairement son propre wire lorsqu'aucune interface officielle KSP correspondante n'existe encore.
## Program / Execution ## Program / Execution
- **DEP-PROGRAM-001** — `ksp-program-api` peut dépendre de `ksp-core-lib` et `ksp-interface-lib`. - **DEP-PROGRAM-001** — `ksp-program-api` peut dépendre de `ksp-core-lib` et `ksp-interface-lib`.
- **DEP-PROGRAM-002** — `ksp-program-lib` dépend de `ksp-program-api` et peut dépendre de `ksp-interface-lib`/`ksp-core-lib`. - **DEP-PROGRAM-002** — `ksp-program-lib` dépend de `ksp-program-api` et peut dépendre de `ksp-interface-lib`/`ksp-core-lib`.
- **DEP-PROGRAM-003** — `ksp-program-api` et `ksp-program-lib` ne dépendent pas du wallet, du transport, du store ou des materializers. - **DEP-PROGRAM-003** — `ksp-program-api` et `ksp-program-lib` ne dépendent pas du wallet, du transport, du store ou des materializers.
- **DEP-PROGRAM-004** — Une implémentation externe `ksp-program-<name>-lib` peut dépendre directement de `ksp-program-api` sans dépendre de `ksp-program-lib`.
- **DEP-EXECUTION-001** — `ksp-execution-policy-api` dépend du contrat public Program, pas de l'implémentation `ksp-program-lib`. - **DEP-EXECUTION-001** — `ksp-execution-policy-api` dépend du contrat public Program, pas de l'implémentation `ksp-program-lib`.
- **DEP-EXECUTION-002** — `ksp-execution-lib` dépend de `ksp-program-api`, `ksp-execution-policy-api`, `ksp-wallet-lib` et `ksp-onchain-transport-lib`; il ne dépend pas de `ksp-program-lib`. - **DEP-EXECUTION-002** — `ksp-execution-lib` dépend de `ksp-program-api`, `ksp-execution-policy-api`, `ksp-wallet-lib` et `ksp-onchain-transport-lib`; il ne dépend pas de `ksp-program-lib`.
- **DEP-EXECUTION-003** — Une implémentation de policy reste située dans une crate de scénario/domaine/produit appropriée et ne devient pas une responsabilité de `ksp-program-lib`. - **DEP-EXECUTION-003** — Une implémentation de policy reste située dans une crate de scénario/domaine/produit appropriée et ne devient pas une responsabilité de `ksp-program-lib`.

15
docs/rules/RULES_KSP.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/RULES_KSP.md --> <!-- file: docs/rules/RULES_KSP.md -->
<!-- version: 7 --> <!-- version: 8 -->
# Règles spécifiques à KSP # Règles spécifiques à KSP
@@ -27,7 +27,7 @@
## Programmes et exécution ## Programmes et exécution
- **KSP-PROGRAM-001** — Les contrats decoder/executor appartiennent à `ksp-program-api`; les implémentations officielles intégrées appartiennent à `ksp-program-lib`. - **KSP-PROGRAM-001** — Les contrats de décodage et de préparation d'exécution appartiennent à `ksp-program-api`; les implémentations officielles intégrées appartiennent à `ksp-program-lib`.
- **KSP-PROGRAM-002** — Le decoder vise toute surface techniquement décodable dont la définition est connue, y compris les formats anciens, obsolètes ou expérimentaux encore distinguables. - **KSP-PROGRAM-002** — Le decoder vise toute surface techniquement décodable dont la définition est connue, y compris les formats anciens, obsolètes ou expérimentaux encore distinguables.
- **KSP-PROGRAM-003** — Le statut `deprecated` concerne la capacité d'exécution, pas la capacité de décodage. - **KSP-PROGRAM-003** — Le statut `deprecated` concerne la capacité d'exécution, pas la capacité de décodage.
- **KSP-PROGRAM-004** — Lorsqu'une définition wire a été réellement écrasée/remplacée sous la même identité et que l'ancienne définition n'est plus distinguable de manière fiable, le decoder utilise la définition la plus récente applicable. - **KSP-PROGRAM-004** — Lorsqu'une définition wire a été réellement écrasée/remplacée sous la même identité et que l'ancienne définition n'est plus distinguable de manière fiable, le decoder utilise la définition la plus récente applicable.
@@ -49,6 +49,17 @@
- **KSP-WALLET-001** — KSP ne crée pas de `ksp-wallet-api` dans l'architecture actuelle ; `ksp-wallet-lib` possède le format wallet KSP et ses capacités de lecture/protection/import/export/pubkey/secret/signature. - **KSP-WALLET-001** — KSP ne crée pas de `ksp-wallet-api` dans l'architecture actuelle ; `ksp-wallet-lib` possède le format wallet KSP et ses capacités de lecture/protection/import/export/pubkey/secret/signature.
- **KSP-PROGRAM-007** — Le contrat de préparation d'exécution est nommé conceptuellement `ProgramExecutionPreparer`; il ne signe, ne simule, n'envoie et ne confirme pas une transaction.
- **KSP-PROGRAM-008** — `ksp-program-api` reste ouvert : aucun enum central fermé ne doit imposer une modification de l'API pour ajouter un Program ID externe.
- **KSP-PROGRAM-009** — Le résultat décodé doit pouvoir être auto-identifié et devenir persistable ; `Any` ne constitue pas à lui seul un contrat de résultat acceptable.
- **KSP-PROGRAM-010** — Une extension de programme est une implémentation `ksp-program-<name>-lib`, pas une nouvelle crate `*-api`.
- **KSP-PROGRAM-011** — `ksp-program-lib` est organisé selon `domain -> program/protocol -> capability`; les dossiers globaux regroupant tous les decoders de tous les protocoles sont évités.
- **KSP-PROGRAM-012** — Le statut legacy/deprecated d'une opération est machine-readable et indépendant du décodage historique.
- **KSP-PROGRAM-013** — `#[deprecated]` n'est pas imposé pour les opérations historiques ; un warning runtime et la policy supérieure peuvent porter la décision d'usage.
- **KSP-WIRE-001** — `ksp-interface-lib` est le propriétaire normal des codecs wire pour les interfaces officielles KSP.
- **KSP-WIRE-002** — Les interfaces externes sont sélectionnées aussi selon la modernité/cohérence de leur graphe de dépendances, pas uniquement selon la commodité de leur API.
- **KSP-WIRE-003** — Les contrats wire d'une crate protocolaire rejetée sont réimplémentés de manière bornée dans `ksp-interface-lib` lorsque KSP en a besoin.
## Workers ## Workers
- **KSP-WORKER-001** — Un worker représente un service continu/live ; il est distinct d'un job. - **KSP-WORKER-001** — Un worker représente un service continu/live ; il est distinct d'un job.

5
prompts/001-V0_1_X_START_PROMPT.md
View File

@@ -1,5 +1,5 @@
<!-- file: prompts/001-V0_1_X_START_PROMPT.md --> <!-- file: prompts/001-V0_1_X_START_PROMPT.md -->
<!-- version: 5 --> <!-- version: 6 -->
# Prompt de démarrage KSP 0.1.x # Prompt de démarrage KSP 0.1.x
@@ -33,7 +33,7 @@ Ces objectifs pourront être répartis entre plusieurs releases `0.1.N`.
## 5. Sources de vérité ## 5. Sources de vérité
Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `005`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`. Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `006`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`.
## 6. Décisions acquises pertinentes ## 6. Décisions acquises pertinentes
@@ -47,6 +47,7 @@ Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PR
- Les exécutables ne dépendent pas directement de crates Solana/protocoles externes. - Les exécutables ne dépendent pas directement de crates Solana/protocoles externes.
- `ksp-core-lib` doit posséder les Program IDs fondamentaux et le type d'erreur commun. - `ksp-core-lib` doit posséder les Program IDs fondamentaux et le type d'erreur commun.
- Les dépendances basses suivent le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md` ; N1 ne doit pas dépendre de ses consommateurs supérieurs. - Les dépendances basses suivent le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md` ; N1 ne doit pas dépendre de ses consommateurs supérieurs.
- KSP évite les générations anciennes/dupliquées évitables de dépendances fondamentales ; toute contrainte de version non actuelle doit être motivée par un besoin réel.
- Les règles fines de naming/arborescence/API publique seront définies à partir des premières APIs réelles. - Les règles fines de naming/arborescence/API publique seront définies à partir des premières APIs réelles.
## 7. Hors périmètre de la série N1 ## 7. Hors périmètre de la série N1