v0.0.3-pre.003
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/000-README.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Architecture KSP
|
||||
|
||||
@@ -20,6 +20,7 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
|
||||
1. [`001-PROJECT_OBJECTIVES.md`](001-PROJECT_OBJECTIVES.md) — finalité, objectifs produits et non-objectifs architecturaux ;
|
||||
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 ;
|
||||
4. [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) — premier inventaire 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.
|
||||
|
||||
L'inventaire `004` est volontairement révisable pendant `0.0.3-pre.003` lorsque le graphe de dépendances révélera des frontières à corriger.
|
||||
`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.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# 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.
|
||||
|
||||
L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md).
|
||||
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).
|
||||
|
||||
## Convention API / implémentation
|
||||
|
||||
@@ -45,7 +45,7 @@ Aucune API commune worker+job n'est prévue.
|
||||
|
||||
`ksp-program-lib` ne possède pas la politique de sécurité/autorisation d'un produit.
|
||||
|
||||
La direction retenue pour étude est un contrat public séparé :
|
||||
Le contrat public séparé suivant est retenu :
|
||||
|
||||
```text
|
||||
ksp-execution-policy-api
|
||||
@@ -57,7 +57,7 @@ Les applications UI sélectionnent/injectent une implémentation réutilisable a
|
||||
|
||||
## Execution orchestration
|
||||
|
||||
`ksp-execution-lib` devient un candidat fort de pipeline/orchestrateur spécialisé pour relier :
|
||||
`ksp-execution-lib` est retenu comme pipeline/orchestrateur spécialisé pour relier :
|
||||
|
||||
- la préparation/sémantique programme ;
|
||||
- une implémentation de `ksp-execution-policy-api` ;
|
||||
@@ -66,7 +66,17 @@ Les applications UI sélectionnent/injectent une implémentation réutilisable a
|
||||
|
||||
Le but est d'éviter que `ksp-program-lib` dépende directement du wallet/transport uniquement pour réaliser le cycle réseau/signature.
|
||||
|
||||
Le graphe exact reste à valider dans `pre.003`.
|
||||
`ksp-execution-lib` dépend de `ksp-program-api` mais pas de `ksp-program-lib` ; il reçoit une opération préparée ou une implémentation conforme au contrat public. Le graphe détaillé est fixé dans `005-DEPENDENCY_GRAPH.md` et les types exacts seront définis en `pre.004`.
|
||||
|
||||
## Frontière materializer / store
|
||||
|
||||
`ksp-materializer-api` peut dépendre de `ksp-program-api` pour consommer des contrats de processing communs.
|
||||
|
||||
`ksp-materializer-lib` reste une bibliothèque de transformation et ne dépend ni de `ksp-store-api` ni de `ksp-store-lib`.
|
||||
|
||||
`ksp-store-api` possède les DTO/contrats persistants et reste indépendant des APIs Program/Materializer. Les workers de processing convertissent explicitement entre modèles runtime et modèles persistants.
|
||||
|
||||
Cette règle évite d'introduire un `ksp-data-api` monolithique uniquement pour partager des modèles entre couches.
|
||||
|
||||
## Transport on-chain
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# 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 ne fige pas encore le graphe exact des dépendances. `0.0.3-pre.003` doit explicitement pouvoir corriger cet inventaire lorsque l'étude des dépendances montre qu'une API, une bibliothèque ou une frontière doit être déplacée, séparée ou supprimée.
|
||||
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.
|
||||
|
||||
## Statuts
|
||||
|
||||
@@ -21,40 +21,40 @@ Il ne fige pas encore le graphe exact des dépendances. `0.0.3-pre.003` doit exp
|
||||
|
||||
## Inventaire synthétique
|
||||
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés |
|
||||
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Candidat fort | `0.2.x–0.4.x` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution |
|
||||
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Candidat fort | `0.2.x–0.4.x` | orchestration spécialisée entre opération préparée, policy, wallet et transport |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
|
||||
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
|
||||
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
|
||||
| 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 |
|
||||
| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries |
|
||||
| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus |
|
||||
| Worker control | `ksp-worker-control-lib` | lib | N3 | Candidat fort | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur |
|
||||
| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data |
|
||||
| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
|
||||
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
|
||||
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
|
||||
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
|
||||
| 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 |
|
||||
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
|
||||
| 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 Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
|
||||
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés |
|
||||
| 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 |
|
||||
| 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 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 |
|
||||
| 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 |
|
||||
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
|
||||
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
|
||||
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
|
||||
| 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 |
|
||||
| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries |
|
||||
| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus |
|
||||
| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur |
|
||||
| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data |
|
||||
| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
|
||||
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
|
||||
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
|
||||
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
|
||||
| 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 |
|
||||
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
|
||||
| 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 Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
|
||||
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
|
||||
| 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
|
||||
|
||||
@@ -77,7 +77,7 @@ Aucune API commune worker+job n'est prévue.
|
||||
|
||||
## Execution policy et orchestration
|
||||
|
||||
### Direction retenue pour étude en `pre.003`
|
||||
### Direction retenue après `pre.003`
|
||||
|
||||
La direction privilégiée est une orchestration supérieure plutôt qu'une dépendance directe de `ksp-program-lib` vers le wallet et le transport :
|
||||
|
||||
@@ -106,7 +106,7 @@ Une application UI ne doit pas enfouir cette logique dans ses commandes ou compo
|
||||
|
||||
Aucune `ksp-execution-policy-lib` générique n'est retenue actuellement. Des implémentations réutilisables pourront être créées plus tard si plusieurs consommateurs partagent réellement la même politique.
|
||||
|
||||
Le graphe exact `ksp-execution-lib -> ksp-program-api` ou `ksp-program-lib`, ainsi que la forme des plans/opérations préparées, est explicitement reporté à `pre.003/pre.004`.
|
||||
`ksp-execution-lib` dépend de `ksp-program-api` et non de `ksp-program-lib`. La forme exacte des plans/opérations préparées et le mécanisme d'injection/appel sont reportés à `pre.004`.
|
||||
|
||||
## Transport on-chain
|
||||
|
||||
@@ -260,12 +260,22 @@ Chaque application appelle la crate `ksp-scenario-<domain>-lib` correspondante e
|
||||
|
||||
Des pipelines spécialisés peuvent être créés à la demande lorsqu'un flux concret possède assez de logique réutilisable pour justifier sa propre frontière. Leur forme n'est pas nécessairement une bibliothèque : certains pourront être workers, jobs ou composants spécialisés.
|
||||
|
||||
## Questions explicitement reportées à `pre.003`
|
||||
## Corrections issues de `pre.003`
|
||||
|
||||
- dépendance exacte de `ksp-execution-lib` vers `ksp-program-api` et/ou `ksp-program-lib` ;
|
||||
- forme du contrat entre program preparation, execution policy, wallet et transport ;
|
||||
- emplacement exact des modèles communs nécessaires à l'exécution ;
|
||||
- types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ;
|
||||
- dépendances autorisées de `ksp-materializer-api` et `ksp-store-api` ;
|
||||
- risque de cycles entre program, materializer, store, execution et control ;
|
||||
- position exacte des notifications de données dans le graphe.
|
||||
Le graphe confirme les principes suivants :
|
||||
|
||||
- Program et Materializer restent indépendants du store et des I/O réseau ;
|
||||
- `ksp-execution-policy-api` et `ksp-execution-lib` sont retenus ;
|
||||
- `ksp-execution-lib` consomme `ksp-program-api`, pas l'implémentation officielle `ksp-program-lib` ;
|
||||
- `ksp-materializer-api` peut dépendre de `ksp-program-api`, mais ni Materializer API/lib ni Store API/lib ne se dépendent mutuellement ;
|
||||
- les workers/jobs spécialisés réalisent les conversions explicites entre modèles de transport, processing et persistence ;
|
||||
- aucun `ksp-data-api` global n'est introduit ;
|
||||
- `ksp-worker-control-lib` est retenu comme gouvernance workers réutilisable ; aucune `ksp-job-control-lib` n'est retenue.
|
||||
|
||||
## Questions reportées aux prereleases suivantes
|
||||
|
||||
- `pre.004` : forme exacte du contrat entre program preparation, execution policy, wallet et transport ;
|
||||
- `pre.004` : types publics précis de `ksp-program-api` et policy ;
|
||||
- `pre.005` : types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ;
|
||||
- `pre.005` : modèles materializer/store, notifications, replay et provenance ;
|
||||
- `pre.006` : managers/apps/processus/IPC, norme des scenarios et orchestrateur futur.
|
||||
|
||||
637
docs/architecture/005-DEPENDENCY_GRAPH.md
Normal file
637
docs/architecture/005-DEPENDENCY_GRAPH.md
Normal file
@@ -0,0 +1,637 @@
|
||||
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Graphe de dépendances KSP
|
||||
|
||||
## Objet
|
||||
|
||||
Ce document constitue la sortie principale de `0.0.3-pre.003`.
|
||||
|
||||
Il répond à la question : **quels composants peuvent dépendre de quels autres composants, et où doivent se produire la composition, l'I/O et les conversions de modèles ?**
|
||||
|
||||
Convention des graphes :
|
||||
|
||||
```text
|
||||
A -> B
|
||||
```
|
||||
|
||||
signifie : **A peut dépendre de B**.
|
||||
|
||||
Le graphe exprime une direction architecturale. Une dépendance autorisée n'est pas obligatoire si l'implémentation peut rester plus faible.
|
||||
|
||||
## Principes structurants
|
||||
|
||||
### 1. APIs sous les implémentations
|
||||
|
||||
Une crate `ksp-<domain>-api` est placée sous les implémentations de son domaine.
|
||||
|
||||
```text
|
||||
implementation -> domain-api
|
||||
```
|
||||
|
||||
Une API publique ne dépend pas de son implémentation officielle.
|
||||
|
||||
### 2. Transformations séparées de l'I/O
|
||||
|
||||
Les bibliothèques de sémantique/transformation comme `ksp-program-lib` et `ksp-materializer-lib` ne deviennent pas propriétaires :
|
||||
|
||||
- du transport réseau ;
|
||||
- du wallet ;
|
||||
- du backend PostgreSQL ;
|
||||
- du lifecycle d'un worker/job.
|
||||
|
||||
Les workers, jobs, scenarios et pipelines spécialisés composent ces capacités lorsqu'ils ont réellement besoin d'I/O.
|
||||
|
||||
### 3. Modèles de domaine distincts des DTO persistants
|
||||
|
||||
KSP ne crée pas actuellement un `ksp-data-api` global.
|
||||
|
||||
Chaque frontière possède les modèles nécessaires à sa responsabilité :
|
||||
|
||||
- transport : modèles homogènes de transport ;
|
||||
- program : contrats de décodage/opération préparée ;
|
||||
- materializer : entrées/sorties de matérialisation ;
|
||||
- store : modèles persistants et références de données persistées.
|
||||
|
||||
La conversion entre ces modèles est explicite dans la couche qui relie les deux responsabilités, principalement les workers/jobs spécialisés.
|
||||
|
||||
### 4. Composition supérieure pour l'exécution
|
||||
|
||||
`ksp-program-lib` ne dépend pas de `ksp-wallet-lib` ou de `ksp-onchain-transport-lib`.
|
||||
|
||||
Le cycle signature/simulation/envoi/confirmation est composé au-dessus, par `ksp-execution-lib`.
|
||||
|
||||
### 5. Workers et jobs restent deux familles
|
||||
|
||||
`ksp-worker-api` et `ksp-job-api` n'ont pas de parent lifecycle commun.
|
||||
|
||||
Un orchestrateur futur peut consommer les deux familles séparément sans les fusionner.
|
||||
|
||||
---
|
||||
|
||||
# Graphe fondations N1
|
||||
|
||||
```text
|
||||
ksp-core-lib
|
||||
|
||||
ksp-config-lib -> ksp-core-lib
|
||||
ksp-logging-lib -> ksp-core-lib
|
||||
ksp-interface-lib -> ksp-core-lib
|
||||
```
|
||||
|
||||
`ksp-core-lib` ne dépend d'aucun composant KSP supérieur.
|
||||
|
||||
`ksp-interface-lib` est propriétaire de la façade wire et peut dépendre des crates externes Solana/interface explicitement autorisées par `RULES_DEPENDENCIES.md`.
|
||||
|
||||
`ksp-config-lib` et `ksp-logging-lib` sont transversaux. Les composants supérieurs peuvent les consommer lorsqu'un besoin réel existe ; cette possibilité ne doit pas être transformée en dépendance obligatoire universelle.
|
||||
|
||||
---
|
||||
|
||||
# Graphe Program
|
||||
|
||||
```text
|
||||
ksp-program-api
|
||||
-> ksp-core-lib
|
||||
-> ksp-interface-lib
|
||||
|
||||
ksp-program-lib
|
||||
-> ksp-program-api
|
||||
-> ksp-interface-lib
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
## Frontière de `ksp-program-api`
|
||||
|
||||
`ksp-program-api` doit porter les contrats publics nécessaires à une implémentation externe de decoder/executor.
|
||||
|
||||
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.
|
||||
|
||||
Noms exacts à définir en `pre.004`, par exemple conceptuellement :
|
||||
|
||||
```text
|
||||
PreparedProgramOperation
|
||||
ProgramExecutionPlan
|
||||
```
|
||||
|
||||
Le choix du nom/type final n'est pas décidé ici.
|
||||
|
||||
## Interdictions Program
|
||||
|
||||
```text
|
||||
ksp-program-api -X-> ksp-wallet-lib
|
||||
ksp-program-api -X-> ksp-onchain-transport-lib
|
||||
ksp-program-api -X-> ksp-store-api
|
||||
ksp-program-api -X-> ksp-materializer-api
|
||||
|
||||
ksp-program-lib -X-> ksp-wallet-lib
|
||||
ksp-program-lib -X-> ksp-onchain-transport-lib
|
||||
ksp-program-lib -X-> ksp-store-api
|
||||
ksp-program-lib -X-> ksp-store-lib
|
||||
ksp-program-lib -X-> ksp-materializer-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.
|
||||
|
||||
---
|
||||
|
||||
# Graphe Execution / Policy
|
||||
|
||||
`ksp-execution-policy-api` et `ksp-execution-lib` sont retenus comme composants.
|
||||
|
||||
```text
|
||||
ksp-execution-policy-api
|
||||
-> ksp-program-api
|
||||
-> ksp-core-lib
|
||||
|
||||
ksp-execution-lib
|
||||
-> ksp-program-api
|
||||
-> ksp-execution-policy-api
|
||||
-> ksp-wallet-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
## Décision importante
|
||||
|
||||
`ksp-execution-lib` **ne dépend pas de `ksp-program-lib`**.
|
||||
|
||||
Il consomme le contrat public de `ksp-program-api` et reçoit :
|
||||
|
||||
- soit une opération préparée conforme à ce contrat ;
|
||||
- soit une implémentation injectée du contrat public lorsque l'API finale le justifie.
|
||||
|
||||
La forme exacte sera décidée en `pre.004`.
|
||||
|
||||
Cette règle permet :
|
||||
|
||||
```text
|
||||
ksp-program-lib ------------------\
|
||||
external-program-implementation ---+--> ksp-program-api --> execution
|
||||
other-compatible-implementation ---/
|
||||
```
|
||||
|
||||
sans rendre l'orchestration dépendante de l'implémentation officielle.
|
||||
|
||||
## Policy
|
||||
|
||||
`ksp-execution-policy-api` définit le contrat d'évaluation, pas la policy d'un produit.
|
||||
|
||||
Une implémentation peut appartenir à :
|
||||
|
||||
- `ksp-scenario-<domain>-lib` pour une demo/scenario Devnet ;
|
||||
- une future bibliothèque de domaine pour une application générale ;
|
||||
- une future bibliothèque trading spécialisée.
|
||||
|
||||
Aucune `ksp-execution-policy-lib` générique n'est prévue tant qu'une policy commune réelle n'existe pas.
|
||||
|
||||
Une policy :
|
||||
|
||||
- autorise/refuse/contraint une exécution ;
|
||||
- ne signe pas ;
|
||||
- ne choisit pas le backend réseau ;
|
||||
- n'envoie pas elle-même une transaction.
|
||||
|
||||
---
|
||||
|
||||
# Graphe Wallet
|
||||
|
||||
```text
|
||||
ksp-wallet-lib
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
`ksp-wallet-lib` peut consommer config/logging si nécessaire à son implémentation, sans que ces dépendances deviennent partie obligatoire du contrat wallet.
|
||||
|
||||
Interdictions :
|
||||
|
||||
```text
|
||||
ksp-wallet-lib -X-> ksp-program-lib
|
||||
ksp-wallet-lib -X-> ksp-execution-lib
|
||||
ksp-wallet-lib -X-> ksp-store-lib
|
||||
```
|
||||
|
||||
Le wallet fournit les capacités de clés/signature ; il n'orchestre pas une opération Solana.
|
||||
|
||||
---
|
||||
|
||||
# Graphe Transport
|
||||
|
||||
## On-chain
|
||||
|
||||
```text
|
||||
ksp-onchain-transport-lib
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
Il peut consommer config/logging lorsque nécessaire.
|
||||
|
||||
Il peut posséder plusieurs familles internes :
|
||||
|
||||
```text
|
||||
HTTP RPC
|
||||
WS RPC
|
||||
Helius advanced
|
||||
Yellowstone
|
||||
...
|
||||
```
|
||||
|
||||
sans créer `ksp-onchain-transport-api`.
|
||||
|
||||
### Modèles homogènes
|
||||
|
||||
Chaque famille provider convertit ses réponses propriétaires vers des modèles KSP homogènes **à l'intérieur de la frontière transport**.
|
||||
|
||||
Exemple conceptuel :
|
||||
|
||||
```text
|
||||
Solana RPC ------\
|
||||
Helius -----------+--> transport raw model
|
||||
Yellowstone ------/
|
||||
```
|
||||
|
||||
Ces modèles :
|
||||
|
||||
- sont indépendants du store ;
|
||||
- conservent le raw et la provenance nécessaire ;
|
||||
- sont faciles à convertir vers les modèles persistants.
|
||||
|
||||
Interdiction ferme :
|
||||
|
||||
```text
|
||||
ksp-onchain-transport-lib -X-> ksp-store-api
|
||||
ksp-onchain-transport-lib -X-> ksp-store-lib
|
||||
```
|
||||
|
||||
## Off-chain
|
||||
|
||||
```text
|
||||
ksp-offchain-transport-lib
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
Config/logging sont autorisés selon le besoin.
|
||||
|
||||
La crate reste volontairement hétérogène. Aucun `ksp-offchain-transport-api` global n'est introduit.
|
||||
|
||||
---
|
||||
|
||||
# Graphe Materialization
|
||||
|
||||
```text
|
||||
ksp-materializer-api
|
||||
-> ksp-core-lib
|
||||
-> ksp-program-api
|
||||
|
||||
ksp-materializer-lib
|
||||
-> ksp-materializer-api
|
||||
-> ksp-program-api
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
`ksp-interface-lib` peut être consommée par `ksp-materializer-lib` lorsqu'une matérialisation a réellement besoin d'un contrat wire déjà possédé par KSP, mais ne doit pas devenir une dépendance obligatoire de toute matérialisation.
|
||||
|
||||
## Décision importante
|
||||
|
||||
Ni `ksp-materializer-api` ni `ksp-materializer-lib` ne dépendent du store.
|
||||
|
||||
```text
|
||||
ksp-materializer-api -X-> ksp-store-api
|
||||
ksp-materializer-lib -X-> ksp-store-api
|
||||
ksp-materializer-lib -X-> ksp-store-lib
|
||||
```
|
||||
|
||||
Une matérialisation transforme des données ; le worker/job/pipeline spécialisé persiste le résultat.
|
||||
|
||||
Cette séparation permet également de tester un materializer externe sans PostgreSQL.
|
||||
|
||||
---
|
||||
|
||||
# Graphe Store
|
||||
|
||||
```text
|
||||
ksp-store-api
|
||||
-> ksp-core-lib
|
||||
|
||||
ksp-store-lib
|
||||
-> ksp-store-api
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
`ksp-store-lib` peut dépendre de config/logging et contient PostgreSQL comme implémentation de référence.
|
||||
|
||||
## Indépendance du store
|
||||
|
||||
Le store ne dépend pas des implémentations Program/Materializer/Transport :
|
||||
|
||||
```text
|
||||
ksp-store-api -X-> ksp-program-api
|
||||
ksp-store-api -X-> ksp-materializer-api
|
||||
ksp-store-api -X-> ksp-onchain-transport-lib
|
||||
|
||||
ksp-store-lib -X-> ksp-program-lib
|
||||
ksp-store-lib -X-> ksp-materializer-lib
|
||||
ksp-store-lib -X-> ksp-onchain-transport-lib
|
||||
```
|
||||
|
||||
`ksp-store-api` définit les DTO/contrats persistants nécessaires aux niveaux durables sans imposer les modèles runtime des processors.
|
||||
|
||||
## Notifications de données persistées
|
||||
|
||||
`ksp-store-api` est retenu comme propriétaire du contrat canonique de notification lorsqu'il signifie :
|
||||
|
||||
> une donnée persistée de telle catégorie est disponible.
|
||||
|
||||
Le même contrat est utilisé quelle que soit l'origine :
|
||||
|
||||
```text
|
||||
live worker ----\
|
||||
backfill job ----+--> persisted data notification
|
||||
import ----------/
|
||||
```
|
||||
|
||||
Le mécanisme de diffusion reste hors du contrat :
|
||||
|
||||
```text
|
||||
channel
|
||||
LISTEN/NOTIFY
|
||||
IPC
|
||||
broker
|
||||
...
|
||||
```
|
||||
|
||||
Le mode de transport concret sera détaillé en `pre.005`.
|
||||
|
||||
---
|
||||
|
||||
# Graphe lifecycle Worker
|
||||
|
||||
```text
|
||||
ksp-worker-api
|
||||
-> ksp-core-lib
|
||||
|
||||
ksp-worker-control-lib
|
||||
-> ksp-worker-api
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
`ksp-worker-control-lib` ne dépend pas des workers concrets. Il fournit une gouvernance réutilisable au-dessus de l'API.
|
||||
|
||||
Les managers/apps/orchestrateurs composent les implémentations concrètes avec cette bibliothèque.
|
||||
|
||||
Interdictions :
|
||||
|
||||
```text
|
||||
ksp-worker-api -X-> ksp-job-api
|
||||
ksp-worker-control-lib -X-> ksp-job-api
|
||||
```
|
||||
|
||||
Le contrôle des jobs ne fuit pas dans la gouvernance workers.
|
||||
|
||||
---
|
||||
|
||||
# Graphe lifecycle Job
|
||||
|
||||
```text
|
||||
ksp-job-api
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est prévue actuellement.
|
||||
|
||||
Interdictions :
|
||||
|
||||
```text
|
||||
ksp-job-api -X-> ksp-worker-api
|
||||
ksp-job-api -X-> ksp-worker-control-lib
|
||||
```
|
||||
|
||||
Un futur orchestrateur peut utiliser workers et jobs séparément sans créer de superclass lifecycle commune.
|
||||
|
||||
---
|
||||
|
||||
# Graphe des composants concrets d'acquisition/processing
|
||||
|
||||
Les dépendances ci-dessous décrivent la composition attendue. Les détails de processus/IPC seront approfondis plus tard.
|
||||
|
||||
## `ksp-worker-raw-retriever`
|
||||
|
||||
```text
|
||||
ksp-worker-raw-retriever
|
||||
-> ksp-worker-api
|
||||
-> ksp-config-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-api
|
||||
-> ksp-store-lib
|
||||
-> ksp-logging-lib
|
||||
```
|
||||
|
||||
Responsabilité de conversion :
|
||||
|
||||
```text
|
||||
transport raw model
|
||||
|
|
||||
v
|
||||
store raw persistence model
|
||||
```
|
||||
|
||||
Cette conversion appartient au worker d'acquisition, pas au transport ni au store.
|
||||
|
||||
## `ksp-job-backfill`
|
||||
|
||||
```text
|
||||
ksp-job-backfill
|
||||
-> ksp-job-api
|
||||
-> ksp-config-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-api
|
||||
-> ksp-store-lib
|
||||
-> ksp-logging-lib
|
||||
```
|
||||
|
||||
Il utilise la même famille de DTO raw persistants et la même notification de données persistées que W1.
|
||||
|
||||
## `ksp-worker-core-processor`
|
||||
|
||||
```text
|
||||
ksp-worker-core-processor
|
||||
-> ksp-worker-api
|
||||
-> ksp-program-api
|
||||
-> ksp-program-lib
|
||||
-> ksp-store-api
|
||||
-> ksp-store-lib
|
||||
-> ksp-config-lib
|
||||
-> ksp-logging-lib
|
||||
```
|
||||
|
||||
Il effectue la conversion explicite :
|
||||
|
||||
```text
|
||||
store raw DTO
|
||||
|
|
||||
v
|
||||
program decode input
|
||||
|
|
||||
v
|
||||
program canonical/decode output
|
||||
|
|
||||
v
|
||||
store Core DTO
|
||||
```
|
||||
|
||||
`ksp-program-lib` ne connaît donc pas le store.
|
||||
|
||||
## `ksp-worker-generic-materializer`
|
||||
|
||||
```text
|
||||
ksp-worker-generic-materializer
|
||||
-> ksp-worker-api
|
||||
-> ksp-materializer-api
|
||||
-> ksp-materializer-lib
|
||||
-> ksp-store-api
|
||||
-> ksp-store-lib
|
||||
-> ksp-config-lib
|
||||
-> ksp-logging-lib
|
||||
```
|
||||
|
||||
La frontière exacte des entrées/sorties génériques sera détaillée en `pre.005`.
|
||||
|
||||
## `ksp-worker-domain-projector`
|
||||
|
||||
```text
|
||||
ksp-worker-domain-projector
|
||||
-> ksp-worker-api
|
||||
-> ksp-materializer-api
|
||||
-> ksp-materializer-lib
|
||||
-> ksp-store-api
|
||||
-> ksp-store-lib
|
||||
-> ksp-config-lib
|
||||
-> ksp-logging-lib
|
||||
```
|
||||
|
||||
Son nom reste provisoire.
|
||||
|
||||
Il est propriétaire de la composition entre résultats de matérialisation spécialisée et projections persistantes par domaine ; `ksp-materializer-lib` reste indépendant du backend.
|
||||
|
||||
---
|
||||
|
||||
# Scenarios et applications demo
|
||||
|
||||
Une crate scénario peut composer les capacités nécessaires à son domaine :
|
||||
|
||||
```text
|
||||
ksp-scenario-<domain>-lib
|
||||
-> ksp-program-api
|
||||
-> ksp-program-lib
|
||||
-> ksp-execution-policy-api
|
||||
-> ksp-execution-lib
|
||||
-> ksp-wallet-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-config-lib
|
||||
```
|
||||
|
||||
Toutes ces dépendances ne sont pas obligatoires pour chaque scénario.
|
||||
|
||||
La crate scénario peut implémenter une policy Devnet adaptée à son besoin.
|
||||
|
||||
L'application correspondante reste une interface :
|
||||
|
||||
```text
|
||||
ksp-app-scenario-<domain>-devnet-desk-demo
|
||||
-> ksp-scenario-<domain>-lib
|
||||
```
|
||||
|
||||
Elle peut dépendre de bibliothèques KSP d'interface/configuration strictement nécessaires à son UI, mais ne réimplémente ni scénario ni policy métier.
|
||||
|
||||
---
|
||||
|
||||
# Orchestrateur futur
|
||||
|
||||
Le futur orchestrateur est au-dessus des contrôles spécialisés.
|
||||
|
||||
Conceptuellement :
|
||||
|
||||
```text
|
||||
orchestrator
|
||||
-> ksp-worker-control-lib
|
||||
-> ksp-job-api # séparément, si coordination de jobs nécessaire
|
||||
-> autres contrôles spécialisés au besoin
|
||||
```
|
||||
|
||||
Cette dépendance simultanée ne crée pas d'API lifecycle commune.
|
||||
|
||||
L'orchestrateur coordonne ; il ne fusionne pas les modèles worker/job.
|
||||
|
||||
---
|
||||
|
||||
# Dépendances explicitement non retenues
|
||||
|
||||
Les composants suivants ne sont pas introduits dans le graphe actuel :
|
||||
|
||||
```text
|
||||
ksp-api-lib
|
||||
ksp-onchain-transport-api
|
||||
ksp-offchain-transport-api
|
||||
ksp-wallet-api
|
||||
ksp-scenario-api
|
||||
ksp-job-control-lib
|
||||
ksp-pipeline-lib
|
||||
ksp-data-api
|
||||
```
|
||||
|
||||
Ils pourront être réévalués uniquement si un besoin concret démontre que la frontière actuelle ne suffit plus.
|
||||
|
||||
---
|
||||
|
||||
# Contrôle des cycles
|
||||
|
||||
Le graphe impose notamment :
|
||||
|
||||
```text
|
||||
core
|
||||
<- interface
|
||||
<- program-api
|
||||
<- materializer-api
|
||||
|
||||
store-api
|
||||
<- store-lib
|
||||
|
||||
worker-api
|
||||
<- worker-control
|
||||
|
||||
job-api
|
||||
<- concrete jobs
|
||||
```
|
||||
|
||||
et interdit toute boucle inverse depuis les couches basses vers leurs consommateurs.
|
||||
|
||||
Les conversions entre Program/Materializer/Store ne sont pas résolues par des dépendances croisées mais par des composants de composition explicites.
|
||||
|
||||
---
|
||||
|
||||
# Questions reportées
|
||||
|
||||
`pre.004` doit détailler :
|
||||
|
||||
- noms/types exacts des entrées/sorties de `ksp-program-api` ;
|
||||
- forme exacte de l'opération préparée ;
|
||||
- appel/injection entre program implementation et `ksp-execution-lib` ;
|
||||
- contrat exact de `ksp-execution-policy-api` ;
|
||||
- frontière entre préparation, policy, simulation, signature, envoi et confirmation.
|
||||
|
||||
`pre.005` doit détailler :
|
||||
|
||||
- DTO raw/Core/materialization/projection du store ;
|
||||
- entrées/sorties `ksp-materializer-api` ;
|
||||
- conversion Core runtime <-> store Core ;
|
||||
- notifications et transport de notifications ;
|
||||
- niveaux durables/replay/idempotence/provenance ;
|
||||
- rôle précis des deux workers de matérialisation.
|
||||
|
||||
`pre.006` doit détailler :
|
||||
|
||||
- managers spécialisés ;
|
||||
- processus/IPC éventuels ;
|
||||
- norme des scenarios ;
|
||||
- apps demo ;
|
||||
- orchestrateur futur et pipelines spécialisés.
|
||||
Reference in New Issue
Block a user