v0.0.3-pre.003
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 8
|
||||
# version: 9
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-core-lib"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.0.3-pre.2"
|
||||
version = "0.0.3-pre.3"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
<!-- file: ROADMAP.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Roadmap KSP
|
||||
|
||||
Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues pour y parvenir. Une série `X.Y.x` regroupe une famille fonctionnelle de travaux ; elle peut contenir plusieurs releases concrètes et plusieurs sessions.
|
||||
|
||||
Les décisions architecturales négatives ou de prudence n'apparaissent pas comme des tâches à cocher. Elles sont conservées dans les règles et documents d'architecture.
|
||||
|
||||
## Légende
|
||||
|
||||
- `[ ]` — prévu / non commencé ;
|
||||
@@ -41,8 +43,8 @@ Regrouper les releases consacrées aux fondations N1. La série n'est pas destin
|
||||
- [ ] Introduire `ksp-wallet-lib` et `ksp-app-wallet-desk`.
|
||||
- [ ] Développer la première surface utile de `ksp-interface-lib`.
|
||||
- [ ] Introduire `ksp-program-api` puis `ksp-program-lib`.
|
||||
- [ ] Étudier/introduire `ksp-execution-policy-api` et `ksp-execution-lib` selon le graphe validé.
|
||||
- [ ] Ne pas créer `ksp-onchain-transport-api` ni `ksp-wallet-api` sans nouveau besoin concret.
|
||||
- [ ] Définir `ksp-execution-policy-api` comme contrat de policy commun à plusieurs contextes.
|
||||
- [ ] Introduire `ksp-execution-lib` lorsque le premier cycle d'exécution réel justifie l'orchestration programme/policy/wallet/transport.
|
||||
- [ ] Introduire `ksp-offchain-transport-lib` seulement au premier besoin réel.
|
||||
|
||||
## 0.3.x — Données, stockage et acquisition raw
|
||||
|
||||
182
deltas/0.0.3/pre.003.md
Normal file
182
deltas/0.0.3/pre.003.md
Normal file
@@ -0,0 +1,182 @@
|
||||
<!-- file: deltas/0.0.3/pre.003.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.0.3-pre.003
|
||||
|
||||
## Base requise
|
||||
|
||||
`v0.0.3-pre.002`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Formaliser le graphe de dépendances KSP, corriger l'inventaire `pre.002` lorsque le graphe révèle une frontière plus propre et éliminer les dépendances susceptibles de créer des cycles ou de mélanger sémantique, I/O et persistence.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
`workspace.package.version` passe de :
|
||||
|
||||
```text
|
||||
0.0.3-pre.2
|
||||
```
|
||||
|
||||
à :
|
||||
|
||||
```text
|
||||
0.0.3-pre.3
|
||||
```
|
||||
|
||||
Le header de `Cargo.toml` passe de version 8 à 9.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `docs/architecture/005-DEPENDENCY_GRAPH.md`
|
||||
- `deltas/0.0.3/pre.003.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `Cargo.toml`
|
||||
- `ROADMAP.md`
|
||||
- `docs/architecture/000-README.md`
|
||||
- `docs/architecture/003-COMPONENT_CONTRACTS.md`
|
||||
- `docs/architecture/004-COMPONENT_INVENTORY.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.
|
||||
|
||||
## Corrections du roadmap
|
||||
|
||||
La ligne :
|
||||
|
||||
```text
|
||||
Ne pas créer ksp-onchain-transport-api ni ksp-wallet-api sans nouveau besoin concret
|
||||
```
|
||||
|
||||
est supprimée des tâches à cocher.
|
||||
|
||||
Il s'agit d'une décision architecturale, conservée dans les règles et le graphe, pas d'un livrable.
|
||||
|
||||
## Décisions principales
|
||||
|
||||
### Program
|
||||
|
||||
```text
|
||||
ksp-program-api
|
||||
-> core/interface
|
||||
|
||||
ksp-program-lib
|
||||
-> ksp-program-api
|
||||
```
|
||||
|
||||
Program reste indépendant du wallet, du transport, du store et des materializers.
|
||||
|
||||
### Execution / Policy
|
||||
|
||||
`ksp-execution-policy-api` et `ksp-execution-lib` passent de candidats forts à composants retenus.
|
||||
|
||||
`ksp-execution-lib` dépend de :
|
||||
|
||||
```text
|
||||
ksp-program-api
|
||||
ksp-execution-policy-api
|
||||
ksp-wallet-lib
|
||||
ksp-onchain-transport-lib
|
||||
```
|
||||
|
||||
Il ne dépend pas de `ksp-program-lib`.
|
||||
|
||||
Les implémentations Program officielles ou externes restent substituables derrière `ksp-program-api`.
|
||||
|
||||
### Materializer
|
||||
|
||||
`ksp-materializer-api` peut dépendre de `ksp-program-api`.
|
||||
|
||||
`ksp-materializer-api` et `ksp-materializer-lib` ne dépendent pas du store.
|
||||
|
||||
### Store
|
||||
|
||||
`ksp-store-api` reste indépendant de Program, Materializer et Transport.
|
||||
|
||||
`ksp-store-lib` implémente `ksp-store-api` avec PostgreSQL comme référence.
|
||||
|
||||
Les modèles persistants appartiennent au store ; les workers/jobs effectuent les conversions depuis les modèles de transport/processing.
|
||||
|
||||
Aucun `ksp-data-api` global n'est introduit.
|
||||
|
||||
### Transport
|
||||
|
||||
`ksp-onchain-transport-lib` ne dépend pas du store.
|
||||
|
||||
Les providers normalisent leurs réponses dans des modèles de transport homogènes, ensuite convertis explicitement par `ksp-worker-raw-retriever`.
|
||||
|
||||
### Workers / Jobs
|
||||
|
||||
`ksp-worker-api` et `ksp-job-api` restent des lifecycle APIs séparées.
|
||||
|
||||
`ksp-worker-control-lib` dépend de `ksp-worker-api` et ne contrôle pas les jobs.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est prévue.
|
||||
|
||||
### Notifications
|
||||
|
||||
`ksp-store-api` devient le propriétaire retenu du contrat canonique de notification lorsqu'une donnée persistée est disponible.
|
||||
|
||||
Le contrat reste indépendant du producteur et du mécanisme de diffusion.
|
||||
|
||||
## Frontières de conversion retenues
|
||||
|
||||
```text
|
||||
transport model
|
||||
-> worker/job acquisition
|
||||
-> store raw DTO
|
||||
|
||||
store raw DTO
|
||||
-> core processor
|
||||
-> program API/lib
|
||||
-> store Core DTO
|
||||
|
||||
store Core DTO
|
||||
-> materializer worker
|
||||
-> materializer API/lib
|
||||
-> store materialization/projection DTO
|
||||
```
|
||||
|
||||
Ces conversions explicites empêchent les dépendances croisées entre bibliothèques basses.
|
||||
|
||||
## Questions reportées
|
||||
|
||||
### `pre.004`
|
||||
|
||||
- types exacts decoder/executor ;
|
||||
- opération préparée ;
|
||||
- policy API détaillée ;
|
||||
- cycle exact de `ksp-execution-lib` ;
|
||||
- conformité wire et historique/deprecated.
|
||||
|
||||
### `pre.005`
|
||||
|
||||
- modèles persistants raw/Core/materialization/projection ;
|
||||
- materializer API détaillée ;
|
||||
- notifications et diffusion ;
|
||||
- replay/provenance/idempotence ;
|
||||
- rôle précis des workers de matérialisation.
|
||||
|
||||
### `pre.006`
|
||||
|
||||
- managers/processus/IPC ;
|
||||
- norme scenarios ;
|
||||
- orchestration globale ;
|
||||
- pipelines spécialisés.
|
||||
|
||||
## Validations
|
||||
|
||||
- headers `file:` / `version:` vérifiés sur tous les fichiers Markdown livrés ;
|
||||
- `Cargo.toml` parsé avec succès et version vérifiée à `0.0.3-pre.3` ;
|
||||
- références internes vers `005-DEPENDENCY_GRAPH.md` vérifiées ;
|
||||
- anciennes références à la fausse tâche roadmap vérifiées absentes ;
|
||||
- aucune commande Cargo exécutée : l'archive delta ne contient pas le workspace complet et ne modifie aucun code Rust.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/IDEAS.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Idées à explorer
|
||||
|
||||
@@ -26,9 +26,9 @@ Premiers couples retenus : program, materializer et store. Les APIs worker/job s
|
||||
|
||||
### Execution policy API
|
||||
|
||||
**Status :** En exploration — candidat fort
|
||||
**Status :** Transférée vers une décision/règle
|
||||
|
||||
Étudier `ksp-execution-policy-api` comme contrat commun d'autorisation/safety/policy d'une exécution.
|
||||
`ksp-execution-policy-api` est retenu comme contrat commun d'autorisation/safety/policy d'une exécution.
|
||||
|
||||
Le contrat doit permettre des implémentations différentes selon le contexte, par exemple scenario Devnet, application générale ou futur produit trading.
|
||||
|
||||
@@ -36,11 +36,11 @@ L'UI sélectionne/injecte une implémentation réutilisable ; elle ne doit pas d
|
||||
|
||||
### Execution orchestration
|
||||
|
||||
**Status :** En exploration — candidat fort
|
||||
**Status :** Transférée vers une décision/règle
|
||||
|
||||
Étudier `ksp-execution-lib` comme orchestration spécialisée entre programme, policy, wallet et transport, plutôt qu'une dépendance directe de `ksp-program-lib` vers wallet/transport.
|
||||
`ksp-execution-lib` est retenu comme orchestration spécialisée entre programme, policy, wallet et transport. Il dépend de `ksp-program-api`, pas de l'implémentation `ksp-program-lib`.
|
||||
|
||||
Le graphe exact est reporté à `0.0.3-pre.003`.
|
||||
Les types exacts d'opération préparée et de policy restent à définir en `0.0.3-pre.004`.
|
||||
|
||||
### Scenarios : norme avant API
|
||||
|
||||
@@ -80,6 +80,14 @@ Définir avec les premières crates fonctionnelles les conventions d'arborescenc
|
||||
|
||||
Aucune `ksp-onchain-transport-api` séparée n'est prévue.
|
||||
|
||||
### Modèles communs inter-domaines
|
||||
|
||||
**Status :** À explorer avec l'implémentation
|
||||
|
||||
Aucun `ksp-data-api` global n'est prévu actuellement. Les modèles appartiennent à leur responsabilité (transport, program, materializer, store) et les composants de composition réalisent les conversions explicites.
|
||||
|
||||
Réévaluer seulement si les premières implémentations montrent une duplication réellement nuisible impossible à résoudre sans contrat commun supplémentaire.
|
||||
|
||||
### Off-chain volontairement hétérogène
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
@@ -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.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Plan KSP 0.0.3
|
||||
|
||||
@@ -9,79 +9,92 @@ Transformer le brainstorming KSP en architecture, règles, inventaire et plan su
|
||||
|
||||
## État courant
|
||||
|
||||
`pre.001` est considérée stabilisée et commitée comme `v0.0.3-pre.001`.
|
||||
- `pre.001` — base de planification stabilisée et commitée ;
|
||||
- `pre.002` — inventaire initial des composants ;
|
||||
- `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition.
|
||||
|
||||
`pre.002` produit le premier inventaire des composants et responsabilités. Cet inventaire est volontairement révisable dans `pre.003` lorsque le graphe de dépendances sera étudié.
|
||||
La prochaine tranche prévue est `pre.004`, consacrée à Program/Wire/Execution.
|
||||
|
||||
## Décisions structurantes actuelles
|
||||
|
||||
- `0.1.x`, `0.2.x`, etc. sont des **séries fonctionnelles**, pas des unités de session.
|
||||
- Chaque release concrète d'une série doit être dimensionnée séparément pour une session raisonnable.
|
||||
- `0.1.x`, `0.2.x`, etc. sont des séries fonctionnelles, pas des unités de session.
|
||||
- Chaque release concrète d'une série est dimensionnée séparément.
|
||||
- Les bibliothèques d'implémentation utilisent `ksp-<role>-lib` ; les contrats publics extensibles utilisent `ksp-<domain>-api`.
|
||||
- Program, materializer et store ont un couple API/implémentation séparé.
|
||||
- Workers et jobs ont des lifecycle APIs distinctes.
|
||||
- `ksp-worker-raw-retriever` réalise uniquement l'acquisition live/quasi-live raw.
|
||||
- Le processing futur est séparé en `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector` (nom du dernier provisoire).
|
||||
- Program, Materializer et Store ont un couple API/implémentation séparé.
|
||||
- Workers et jobs ont des lifecycle APIs distinctes, sans parent commun.
|
||||
- `ksp-worker-raw-retriever` réalise uniquement l'acquisition raw live/quasi-live.
|
||||
- `ksp-job-backfill` réalise l'acquisition historique à la demande.
|
||||
- `ksp-worker-control-lib` est destiné à être réutilisé par managers/apps/orchestrateur ; aucune `ksp-job-control-lib` n'est prévue sans besoin concret.
|
||||
- `ksp-execution-policy-api` et `ksp-execution-lib` sont des candidats forts pour séparer policy et orchestration d'exécution de `ksp-program-lib`.
|
||||
- Pas de `ksp-onchain-transport-api`, `ksp-offchain-transport-api` ou `ksp-wallet-api` dans l'architecture actuelle.
|
||||
- `ksp-onchain-transport-lib` expose des modèles de transport homogènes mais indépendants du store.
|
||||
- Pas de `ksp-scenario-api` pour l'instant : privilégier une norme souple de scénarios spécialisés.
|
||||
- Pas de `ksp-pipeline-lib` monolithique ; pipelines spécialisés uniquement à la demande.
|
||||
- Le processing futur est séparé entre `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector`.
|
||||
- `ksp-worker-control-lib` est la gouvernance commune des workers ; aucune `ksp-job-control-lib` n'est prévue actuellement.
|
||||
- `ksp-execution-policy-api` est retenu.
|
||||
- `ksp-execution-lib` est retenu comme orchestration spécialisée et dépend de `ksp-program-api`, pas de `ksp-program-lib`.
|
||||
- `ksp-program-lib` ne dépend ni du wallet ni du transport.
|
||||
- `ksp-materializer-lib` ne dépend pas du store.
|
||||
- `ksp-store-api` reste indépendant de Program/Materializer/Transport.
|
||||
- Les workers/jobs spécialisés convertissent explicitement les modèles entre transport, processing et persistence.
|
||||
- `ksp-store-api` possède les notifications canoniques de données persistées ; leur transport concret reste séparé.
|
||||
- Aucun `ksp-data-api`, `ksp-pipeline-lib`, `ksp-scenario-api`, `ksp-onchain-transport-api`, `ksp-offchain-transport-api` ou `ksp-wallet-api` n'est prévu actuellement.
|
||||
- Les scenarios restent des crates spécialisées régies d'abord par une norme souple.
|
||||
|
||||
## Prévision souple des prereleases restantes
|
||||
|
||||
### `pre.002` — Inventaire initial des composants
|
||||
|
||||
- créer `docs/architecture/004-COMPONENT_INVENTORY.md` ;
|
||||
- fixer les responsabilités et statuts initiaux des composants ;
|
||||
- enregistrer les workers/jobs/scénarios/apps actuellement prévus ;
|
||||
- documenter les candidats `ksp-execution-policy-api` et `ksp-execution-lib` ;
|
||||
- corriger la règle de charge série/release/session ;
|
||||
- préparer explicitement les questions à résoudre dans `pre.003`.
|
||||
|
||||
### `pre.003` — Graphe de dépendances et correction de l'inventaire
|
||||
|
||||
- construire le graphe autorisé/interdit ;
|
||||
- décider si `ksp-execution-lib` dépend de `ksp-program-api`, `ksp-program-lib` ou reçoit des implémentations injectées ;
|
||||
- définir la frontière program -> execution plan -> policy -> wallet/transport ;
|
||||
- vérifier que transport ne dépend pas du store tout en gardant une conversion simple des modèles ;
|
||||
- positionner materializer/store/notifications ;
|
||||
- rechercher et supprimer les cycles ;
|
||||
- corriger `004-COMPONENT_INVENTORY.md` si nécessaire.
|
||||
Livré :
|
||||
|
||||
- `docs/architecture/005-DEPENDENCY_GRAPH.md` ;
|
||||
- graphe Program/Execution/Policy ;
|
||||
- graphe Materializer/Store ;
|
||||
- graphe Worker/Job ;
|
||||
- conversion explicite des modèles aux frontières ;
|
||||
- dépendances interdites et prévention des cycles ;
|
||||
- correction de `004-COMPONENT_INVENTORY.md` ;
|
||||
- suppression des décisions négatives présentées à tort comme tâches du roadmap.
|
||||
|
||||
### `pre.004` — Programmes, wire et exécution
|
||||
|
||||
- détailler `ksp-interface-lib`, `ksp-program-api`, `ksp-program-lib` ;
|
||||
- détailler l'execution policy/orchestration si validées ;
|
||||
- cadrer conformité wire, historique/deprecated et sécurité supérieure.
|
||||
Objectifs prévus :
|
||||
|
||||
- détailler `ksp-interface-lib` ;
|
||||
- détailler `ksp-program-api` et `ksp-program-lib` ;
|
||||
- définir précisément decoder API et executor API ;
|
||||
- définir le contrat d'opération préparée ;
|
||||
- définir `ksp-execution-policy-api` ;
|
||||
- détailler le cycle de `ksp-execution-lib` : préparation, policy, simulation, signature, envoi, confirmation ;
|
||||
- cadrer conformité wire, historique/deprecated et policy supérieure ;
|
||||
- vérifier que la tranche reste dans le budget de complexité, sinon la scinder.
|
||||
|
||||
### `pre.005` — Données, store et acquisitions
|
||||
|
||||
- détailler materializer/store ;
|
||||
- finaliser les modèles raw et notifications ;
|
||||
- détailler `ksp-materializer-api` / `ksp-materializer-lib` ;
|
||||
- détailler `ksp-store-api` / `ksp-store-lib` ;
|
||||
- finaliser modèles raw/Core/generic/domain ;
|
||||
- détailler notifications et mécanismes de diffusion possibles ;
|
||||
- détailler W1 et backfill ;
|
||||
- cadrer les trois workers de processing futurs ;
|
||||
- revisiter les niveaux durables/replay.
|
||||
- cadrer les workers de processing ;
|
||||
- revisiter niveaux durables, replay, provenance et idempotence.
|
||||
|
||||
### `pre.006` — Applications, workers, jobs, scenarios et pipelines spécialisés
|
||||
|
||||
- formaliser les apps spécialisées ;
|
||||
- détailler `ksp-worker-control-lib` ;
|
||||
- définir la norme des crates scénario et leurs apps demo ;
|
||||
- définir la norme des crates scenario et leurs apps demo ;
|
||||
- traiter les processus/IPC/managers ;
|
||||
- cadrer l'orchestrateur futur ;
|
||||
- inventorier les pipelines spécialisés réellement nécessaires.
|
||||
|
||||
### `pre.007` — Plan des premières releases fonctionnelles
|
||||
|
||||
- transformer les séries `0.1.x+` en premières releases concrètes ;
|
||||
- dimensionner chaque release concrète plutôt que toute la série ;
|
||||
- préparer le prompt de la première release `0.1.x` réellement choisie.
|
||||
- dimensionner chaque release concrète ;
|
||||
- choisir la première release `0.1.N` ;
|
||||
- transformer le brouillon de prompt en prompt quasi-final de cette release concrète.
|
||||
|
||||
### `pre.008` — Clôture fondatrice
|
||||
|
||||
- validations finales de cohérence ;
|
||||
- documentation/nettoyage/archivage ;
|
||||
- synchronisation du changelog si applicable ;
|
||||
- finalisation du prompt de la première release fonctionnelle.
|
||||
|
||||
Le nombre de prereleases reste révisable si une tranche dépasse le budget de planification ou si une nouvelle frontière apparaît.
|
||||
Le nombre de prereleases reste révisable si une tranche dépasse le budget de planification ou si une frontière supplémentaire doit être étudiée.
|
||||
|
||||
@@ -1,36 +1,74 @@
|
||||
<!-- file: docs/rules/RULES_DEPENDENCIES.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Règles des dépendances KSP
|
||||
|
||||
## Portée
|
||||
|
||||
Les règles `DEP-*` définissent quelles dépendances externes peuvent traverser les frontières KSP et quelles couches en sont propriétaires.
|
||||
Les règles `DEP-*` définissent quelles dépendances externes et internes peuvent traverser les frontières KSP et quelles couches en sont propriétaires.
|
||||
|
||||
Elles complètent les règles Rust générales. Elles sont particulièrement strictes pour les crates liées à Solana et aux protocoles on-chain.
|
||||
Elles complètent les règles Rust générales et le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md`.
|
||||
|
||||
## Firewall des exécutables
|
||||
|
||||
- **DEP-EXEC-001** — Les applications, demos et workers KSP ne dépendent directement d'aucune crate externe relative à Solana ou à un protocole Solana. Ils consomment exclusivement les bibliothèques KSP propriétaires de ces contrats.
|
||||
- **DEP-EXEC-002** — Une application peut dépendre directement de bibliothèques générales non-Solana nécessaires à son interface ou à son runtime, par exemple UI, sérialisation, Base64 ou Base58, à condition que ces dépendances ne portent pas une opération métier/protocolaire appartenant à KSP.
|
||||
- **DEP-EXEC-003** — Si un exécutable a besoin d'un type, d'une fonction ou d'un contrat Solana, la bibliothèque KSP propriétaire doit l'exposer ou fournir le wrapper/contrat approprié ; l'exécutable ne contourne pas cette frontière en ajoutant lui-même la crate Solana.
|
||||
- **DEP-EXEC-001** — Les applications, demos, workers et jobs KSP ne dépendent directement d'aucune crate externe relative à Solana ou à un protocole Solana. Ils consomment exclusivement les composants KSP propriétaires de ces contrats.
|
||||
- **DEP-EXEC-002** — Un exécutable peut dépendre directement de bibliothèques générales non-Solana nécessaires à son interface ou à son runtime, à condition qu'elles ne portent pas une opération métier/protocolaire appartenant à KSP.
|
||||
- **DEP-EXEC-003** — Si un exécutable a besoin d'un type, d'une fonction ou d'un contrat Solana, le composant KSP propriétaire doit l'exposer ou fournir le wrapper/contrat approprié.
|
||||
|
||||
## Direction des dépendances internes
|
||||
|
||||
- **DEP-KSP-001** — Une crate `ksp-<domain>-api` ne dépend jamais de l'implémentation officielle `ksp-<domain>-lib`.
|
||||
- **DEP-KSP-002** — Une bibliothèque basse de transformation/sémantique ne dépend pas d'un worker, job, application ou orchestrateur qui la consomme.
|
||||
- **DEP-KSP-003** — Les conversions entre modèles de transport, processing et persistence sont réalisées par les composants de composition appropriés plutôt que par des dépendances croisées entre domaines.
|
||||
- **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.
|
||||
|
||||
## Program / Execution
|
||||
|
||||
- **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-003** — `ksp-program-api` et `ksp-program-lib` ne dépendent pas du wallet, du transport, du store ou des materializers.
|
||||
- **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-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`.
|
||||
|
||||
## Materializer / Store
|
||||
|
||||
- **DEP-MAT-001** — `ksp-materializer-api` peut dépendre de `ksp-program-api` lorsque les contrats de matérialisation consomment des sorties canoniques de processing.
|
||||
- **DEP-MAT-002** — `ksp-materializer-api` et `ksp-materializer-lib` ne dépendent pas de `ksp-store-api` ou `ksp-store-lib`.
|
||||
- **DEP-STORE-001** — `ksp-store-api` ne dépend pas de Program, Materializer ou Transport.
|
||||
- **DEP-STORE-002** — `ksp-store-lib` dépend de `ksp-store-api` et contient l'implémentation PostgreSQL de référence ; il ne dépend pas des implémentations Program/Materializer/Transport.
|
||||
- **DEP-STORE-003** — Les workers/jobs spécialisés sont propriétaires des conversions entre modèles runtime et DTO persistants.
|
||||
|
||||
## Transport
|
||||
|
||||
- **DEP-TRANSPORT-001** — `ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api` ou `ksp-store-lib`.
|
||||
- **DEP-TRANSPORT-002** — Les providers on-chain normalisent leurs réponses dans des modèles KSP homogènes par catégorie de données avant exposition aux consommateurs.
|
||||
- **DEP-TRANSPORT-003** — Les modèles de transport ne réalisent pas de décodage métier/protocolaire et doivent rester facilement convertibles en DTO raw persistants.
|
||||
- **DEP-TRANSPORT-004** — Aucun `ksp-onchain-transport-api` ou `ksp-offchain-transport-api` global n'est créé dans l'architecture actuelle.
|
||||
|
||||
## Worker / Job lifecycle
|
||||
|
||||
- **DEP-WORKER-001** — `ksp-worker-control-lib` dépend de `ksp-worker-api` et ne dépend pas de `ksp-job-api`.
|
||||
- **DEP-JOB-001** — `ksp-job-api` ne dépend ni de `ksp-worker-api` ni de `ksp-worker-control-lib`.
|
||||
- **DEP-JOB-002** — Un orchestrateur futur peut consommer séparément les APIs/contrôles workers et jobs sans introduire un lifecycle parent commun.
|
||||
|
||||
## Propriété des dépendances Solana
|
||||
|
||||
- **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir une bibliothèque KSP propriétaire précise. Elle n'est pas ajoutée dans plusieurs couches uniquement parce qu'elle est pratique à utiliser.
|
||||
- **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir un composant KSP propriétaire précis.
|
||||
- **DEP-SOL-002** — Les bibliothèques KSP de haut niveau qui n'ont pas besoin d'un contrat externe bas niveau ne dépendent pas directement de ce contrat.
|
||||
- **DEP-SOL-003** — Les primitives Solana/Anza suffisamment fondamentales et stables peuvent être utilisées dans les bibliothèques KSP de bas niveau qui en sont propriétaires.
|
||||
- **DEP-SOL-004** — La liste initialement acceptée de primitives fondamentales comprend `solana-pubkey`, `solana-keypair`, `solana-signer`, `solana-hash` et `solana-nonce`.
|
||||
- **DEP-SOL-005** — L'ajout d'une autre crate Solana/Anza est décidé à partir d'un besoin concret et de sa stabilité/API ; l'appartenance au dépôt Solana/Anza ne constitue pas à elle seule une autorisation automatique.
|
||||
- **DEP-SOL-006** — Une bibliothèque KSP peut exposer ou réexporter une primitive externe fondamentale lorsque cette primitive fait intentionnellement partie du contrat KSP ; l'exécutable consommateur dépend alors de KSP, pas directement de la crate externe.
|
||||
- **DEP-SOL-005** — L'ajout d'une autre crate Solana/Anza est décidé à partir d'un besoin concret et de sa stabilité/API.
|
||||
- **DEP-SOL-006** — Une bibliothèque KSP peut exposer ou réexporter une primitive externe fondamentale lorsque cette primitive fait intentionnellement partie du contrat KSP.
|
||||
|
||||
## Crates de protocoles et interfaces wire
|
||||
|
||||
- **DEP-PROTO-001** — Les crates d'interface/protocole externes telles que `mpl-token-metadata` ou `spl-elgamal-registry-interface` sont interdites par défaut comme dépendances runtime KSP.
|
||||
- **DEP-PROTO-002** — KSP préfère posséder ses représentations compatibles nécessaires : Program IDs, discriminants, layouts, enums, structures wire, règles de PDA, sérialisation/désérialisation et autres contrats effectivement requis.
|
||||
- **DEP-PROTO-003** — Une réimplémentation KSP vise le contrat nécessaire et ne consiste pas à copier mécaniquement l'architecture ou l'intégralité d'une crate externe.
|
||||
- **DEP-PROTO-004** — La méthode de vérification de compatibilité wire, l'usage éventuel de dépendances externes uniquement en tests de conformité et les contraintes de licence/source de vérité restent à définir avant la première implémentation de protocole concernée.
|
||||
- **DEP-PROTO-005** — Une dépendance protocolaire externe exceptionnellement nécessaire doit être explicitement justifiée, confinée à la bibliothèque propriétaire la plus basse possible et documentée avec sa version, sa raison et sa condition de suppression ou réévaluation.
|
||||
- **DEP-PROTO-004** — La méthode de vérification de compatibilité wire et l'usage éventuel de dépendances externes uniquement en tests de conformité doivent être définis avant la première implémentation concernée.
|
||||
- **DEP-PROTO-005** — Une dépendance protocolaire externe exceptionnellement nécessaire doit être explicitement justifiée et confinée au composant propriétaire le plus bas possible.
|
||||
|
||||
## Versions
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_KSP.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Règles spécifiques à KSP
|
||||
|
||||
@@ -33,9 +33,9 @@
|
||||
- **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-005** — Une opération devenue obsolète mais toujours identifiable/exécutable peut rester implémentée dans l'executor et être marquée `deprecated`.
|
||||
- **KSP-PROGRAM-006** — `ksp-program-lib` ne contient pas la politique de sécurité de production.
|
||||
- **KSP-EXEC-001** — La direction retenue est une API de policy d'exécution séparée, candidate `ksp-execution-policy-api`, afin que plusieurs contextes puissent fournir des politiques différentes sans modifier `ksp-program-lib`.
|
||||
- **KSP-EXEC-001** — `ksp-execution-policy-api` est retenu comme API publique de policy d'exécution afin que plusieurs contextes puissent fournir des politiques différentes sans modifier `ksp-program-lib`.
|
||||
- **KSP-EXEC-002** — Une application UI sélectionne/injecte une implémentation de policy réutilisable ; elle ne doit pas enfouir une politique d'exécution complexe dans sa couche d'interface.
|
||||
- **KSP-EXEC-003** — `ksp-execution-lib` est un candidat fort d'orchestration spécialisée entre programme, policy, wallet et transport. Son graphe exact est reporté à l'étude des dépendances.
|
||||
- **KSP-EXEC-003** — `ksp-execution-lib` est retenu comme orchestration spécialisée entre programme, policy, wallet et transport. Il dépend de `ksp-program-api` et non de `ksp-program-lib`.
|
||||
|
||||
## Transports
|
||||
|
||||
@@ -71,11 +71,18 @@
|
||||
- **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie.
|
||||
- **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers.
|
||||
|
||||
## Matérialisation et persistence
|
||||
|
||||
- **KSP-MAT-001** — `ksp-materializer-api` peut dépendre de `ksp-program-api` ; `ksp-materializer-lib` dépend de son API mais ne dépend pas du store.
|
||||
- **KSP-MAT-002** — `ksp-materializer-api` / `ksp-materializer-lib` ne réalisent pas eux-mêmes la persistance ; les workers/jobs/pipelines spécialisés composent matérialisation et store.
|
||||
- **KSP-STORE-001** — `ksp-store-api` reste indépendant des APIs Program/Materializer/Transport et possède les contrats persistants.
|
||||
- **KSP-STORE-002** — Les conversions entre modèles runtime et DTO persistants sont explicites aux frontières de composition ; aucun `ksp-data-api` global n'est introduit actuellement.
|
||||
|
||||
## Notifications de données
|
||||
|
||||
- **KSP-DATA-001** — Une notification de donnée décrit la donnée disponible et non le worker/job qui l'a produite.
|
||||
- **KSP-DATA-002** — Le même type de donnée utilise le même contrat de notification quelle que soit son origine : worker, job, import ou autre source.
|
||||
- **KSP-DATA-003** — `ksp-store-api` est le propriétaire candidat des références/notifications canoniques de données persistées lorsque ces contrats appartiennent naturellement à la frontière store.
|
||||
- **KSP-DATA-003** — `ksp-store-api` est le propriétaire retenu des références/notifications canoniques lorsqu'elles signifient qu'une donnée persistée est disponible.
|
||||
- **KSP-DATA-004** — Le contrat de notification est séparé de son mécanisme de transport concret.
|
||||
|
||||
## Pipelines et scénarios
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: prompts/001-V0_1_X_START_PROMPT.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# 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é
|
||||
|
||||
Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `004`, 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` à `005`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`.
|
||||
|
||||
## 6. Décisions acquises pertinentes
|
||||
|
||||
@@ -46,6 +46,7 @@ Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PR
|
||||
- Les applications restent des interfaces/compositions.
|
||||
- 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.
|
||||
- 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 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
|
||||
|
||||
Reference in New Issue
Block a user