v0.0.3-pre.002
This commit is contained in:
129
docs/IDEAS.md
129
docs/IDEAS.md
@@ -1,8 +1,19 @@
|
||||
<!-- file: docs/IDEAS.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Idées à explorer
|
||||
|
||||
Ce document conserve les idées, pistes, questions et alternatives qui méritent d'être étudiées sans constituer encore un engagement de développement ou une décision architecturale.
|
||||
|
||||
## Statuts
|
||||
|
||||
- `À explorer`
|
||||
- `En exploration`
|
||||
- `Retenue`
|
||||
- `Rejetée`
|
||||
- `Transférée au roadmap`
|
||||
- `Transférée vers une décision/règle`
|
||||
|
||||
## APIs et extensibilité
|
||||
|
||||
### Nomenclature `*-api`
|
||||
@@ -11,38 +22,41 @@
|
||||
|
||||
Les crates de contrats publics extensibles utilisent `ksp-<domain>-api`, sans suffixe `-lib`.
|
||||
|
||||
Premiers couples retenus :
|
||||
Premiers couples retenus : program, materializer et store. Les APIs worker/job sont des lifecycle APIs distinctes.
|
||||
|
||||
```text
|
||||
ksp-program-api / ksp-program-lib
|
||||
ksp-materializer-api / ksp-materializer-lib
|
||||
ksp-store-api / ksp-store-lib
|
||||
```
|
||||
### Execution policy API
|
||||
|
||||
Éviter un unique `ksp-api-lib` monolithique.
|
||||
**Status :** En exploration — candidat fort
|
||||
|
||||
### APIs workers et jobs
|
||||
Étudier `ksp-execution-policy-api` 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.
|
||||
|
||||
L'UI sélectionne/injecte une implémentation réutilisable ; elle ne doit pas devenir propriétaire d'une politique complexe.
|
||||
|
||||
### Execution orchestration
|
||||
|
||||
**Status :** En exploration — candidat fort
|
||||
|
||||
É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.
|
||||
|
||||
Le graphe exact est reporté à `0.0.3-pre.003`.
|
||||
|
||||
### Scenarios : norme avant API
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Les workers et jobs ont des modèles de lifecycle différents et ne doivent pas partager une API universelle commune.
|
||||
Ne pas créer `ksp-scenario-api` pour l'instant.
|
||||
|
||||
Prévoir séparément :
|
||||
Définir d'abord une norme souple de structure, métadonnées, exécution et résultat des crates `ksp-scenario-<domain>-lib`, sans imposer un trait Rust qui limiterait des scénarios hétérogènes.
|
||||
|
||||
```text
|
||||
ksp-worker-api
|
||||
ksp-job-api
|
||||
```
|
||||
|
||||
`ksp-worker-control-lib` reste un candidat d'implémentation de contrôle des workers uniquement.
|
||||
|
||||
Le besoin éventuel d'une implémentation commune de contrôle des jobs sera évalué séparément.
|
||||
Réévaluer seulement si les premières implémentations révèlent un vrai contrat commun.
|
||||
|
||||
### Type d'erreur KSP unique
|
||||
|
||||
**Status :** En exploration
|
||||
|
||||
La direction retenue est un seul type public `ksp_core_lib::Error` consommable par le workspace, sans obliger `ksp-core-lib` à connaître chaque domaine supérieur.
|
||||
La direction retenue est un seul type public `ksp_core_lib::Error` consommable par le workspace sans obliger `ksp-core-lib` à connaître chaque domaine supérieur.
|
||||
|
||||
### Nommage des items publics
|
||||
|
||||
@@ -54,51 +68,74 @@ Définir avec les premières APIs réelles les conventions de nommage des traits
|
||||
|
||||
**Status :** À explorer
|
||||
|
||||
Définir avec les premières crates fonctionnelles les conventions d'arborescence des modules/fichiers, façades `lib.rs`, modules API et réexports publics.
|
||||
Définir avec les premières crates fonctionnelles les conventions d'arborescence, façades `lib.rs`, modules API et réexports publics.
|
||||
|
||||
## Données et notifications
|
||||
## Transport
|
||||
|
||||
### Notifications normalisées de données
|
||||
### Modèles homogènes on-chain
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Une notification de donnée doit avoir la même représentation canonique pour le même type de donnée quelle que soit son origine.
|
||||
`ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api`, mais ses différents providers doivent exposer des modèles homogènes par catégorie de données afin que `ksp-worker-raw-retriever` puisse les convertir simplement vers les modèles raw persistants du store.
|
||||
|
||||
`ksp-store-api` est le propriétaire candidat de ces contrats lorsque la notification signifie qu'une donnée persistée est disponible.
|
||||
Aucune `ksp-onchain-transport-api` séparée n'est prévue.
|
||||
|
||||
Le transport concret de notification reste indépendant du contrat.
|
||||
|
||||
### Backend PostgreSQL
|
||||
### Off-chain volontairement hétérogène
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
`ksp-store-lib` contient PostgreSQL comme implémentation de référence de `ksp-store-api`.
|
||||
`ksp-offchain-transport-lib` regroupe metadata, prix, quotes, routage et autres accès externes afin d'éviter une explosion de crates. Il n'est pas nécessaire de leur inventer une API métier commune.
|
||||
|
||||
## Workers et jobs
|
||||
|
||||
### W1
|
||||
### Workers de processing
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
W1 reste strictement un worker raw live/quasi-live avec reconfiguration à chaud, persistance raw et notification. Aucun replay/backfill.
|
||||
Après `ksp-worker-raw-retriever`, les responsabilités de processing actuellement prévues sont séparées :
|
||||
|
||||
### Backfill historique
|
||||
- `ksp-worker-core-processor` ;
|
||||
- `ksp-worker-generic-materializer` ;
|
||||
- `ksp-worker-domain-projector` (nom provisoire).
|
||||
|
||||
**Status :** Retenue
|
||||
### Worker control
|
||||
|
||||
Le backfill historique est un job distinct, candidat `ksp-job-backfill`.
|
||||
**Status :** Retenue comme direction
|
||||
|
||||
### Autres jobs
|
||||
`ksp-worker-control-lib` doit être une implémentation réutilisable de gouvernance consommable par des applications desktop manager, une future application globale et l'orchestrateur.
|
||||
|
||||
**Status :** Retenue
|
||||
### Job control
|
||||
|
||||
Des jobs séparés pourront apparaître pour metadata, quotes ou autres traitements ponctuels lorsqu'un besoin réel existe.
|
||||
**Status :** Rejetée pour l'instant
|
||||
|
||||
### Orchestrateur
|
||||
Ne pas créer `ksp-job-control-lib` sans duplication concrète entre plusieurs jobs. `ksp-job-api` suffit comme lifecycle API commune tant que chaque job peut être gouverné directement via son implémentation.
|
||||
|
||||
**Status :** Retenue
|
||||
## Wallet : applications futures
|
||||
|
||||
Commencer par des managers séparés. Introduire un orchestrateur global lorsque plusieurs workers/managers le justifient. Les jobs restent gouvernés par leurs contrats propres.
|
||||
### Wallet Android
|
||||
|
||||
**Status :** À explorer — futur lointain
|
||||
|
||||
Une application Android native utilisant `ksp-wallet-lib` est envisagée. Nom exact à définir plus tard, candidat : `ksp-app-wallet-android`.
|
||||
|
||||
### Extensions navigateur
|
||||
|
||||
**Status :** À explorer — futur lointain
|
||||
|
||||
Prévoir potentiellement des extensions Firefox et Chrome consommant les capacités KSP appropriées. Noms candidats non normatifs :
|
||||
|
||||
```text
|
||||
ksp-app-wallet-firefox-extension
|
||||
ksp-app-wallet-chrome-extension
|
||||
```
|
||||
|
||||
Le modèle de sécurité, la frontière Rust/WebAssembly/native et le stockage des secrets devront être étudiés avant toute décision.
|
||||
|
||||
### Wallet web
|
||||
|
||||
**Status :** À explorer — futur lointain
|
||||
|
||||
Un wallet web/online utilisant les contrats KSP est envisagé. La gestion des secrets et le modèle de confiance devront être traités comme une question architecturale majeure avant développement.
|
||||
|
||||
## Pipelines
|
||||
|
||||
@@ -106,17 +143,7 @@ Commencer par des managers séparés. Introduire un orchestrateur global lorsque
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Ne pas créer de `ksp-pipeline-lib`. Les pipelines sont introduits séparément à la demande avec un périmètre borné.
|
||||
|
||||
## Scénarios
|
||||
|
||||
### Crates spécialisées
|
||||
|
||||
**Status :** Retenue
|
||||
|
||||
Ne pas créer de `ksp-scenarios-lib` monolithique. Utiliser des crates spécialisées `ksp-scenario-<domain>-lib`.
|
||||
|
||||
Memo, Token classique, ATA et Token-2022 restent séparés. Metaplex Token Metadata et Token-2022 Metadata peuvent partager une famille metadata ; Solana Program Metadata reste séparé.
|
||||
Ne pas créer de `ksp-pipeline-lib`. Les pipelines sont introduits séparément à la demande avec un périmètre concret.
|
||||
|
||||
## Trading
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/000-README.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Architecture KSP
|
||||
|
||||
@@ -19,6 +19,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, contrats à définir tôt et responsabilités déjà acquises.
|
||||
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.
|
||||
|
||||
Les futurs documents prioritaires peuvent continuer avec `004-`, `005-`, etc. lorsqu'un ordre de lecture explicite apporte une valeur réelle.
|
||||
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.
|
||||
|
||||
@@ -1,127 +1,144 @@
|
||||
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Contrats initiaux des composants KSP
|
||||
|
||||
## Objet
|
||||
|
||||
Ce document enregistre les frontières déjà suffisamment claires pour guider la planification. Il ne définit pas encore les API Rust finales.
|
||||
|
||||
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).
|
||||
|
||||
## Convention API / implémentation
|
||||
|
||||
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP sépare :
|
||||
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP peut séparer :
|
||||
|
||||
```text
|
||||
ksp-<domain>-api
|
||||
ksp-<domain>-lib
|
||||
```
|
||||
|
||||
La crate `ksp-<domain>-api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`. Elle expose principalement des traits, types, enums et contrats publics ; elle peut être consommée par plusieurs implémentations et n'est pas, à elle seule, une implémentation fonctionnelle destinée aux exécutables.
|
||||
La crate `ksp-<domain>-api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`.
|
||||
|
||||
La crate `ksp-<domain>-lib` contient l'implémentation officielle KSP correspondante lorsqu'une telle implémentation existe.
|
||||
Cette séparation n'est pas automatique. Elle est utilisée lorsqu'une vraie frontière d'extension/backend/lifecycle la justifie.
|
||||
|
||||
Cette séparation n'est pas automatique pour tous les domaines. Elle est utilisée lorsqu'une vraie frontière d'extension ou de backend justifie une API indépendante.
|
||||
Couples retenus :
|
||||
|
||||
Premiers couples retenus :
|
||||
```text
|
||||
ksp-program-api / ksp-program-lib
|
||||
ksp-materializer-api / ksp-materializer-lib
|
||||
ksp-store-api / ksp-store-lib
|
||||
```
|
||||
|
||||
- `ksp-program-api` + `ksp-program-lib` ;
|
||||
- `ksp-materializer-api` + `ksp-materializer-lib` ;
|
||||
- `ksp-store-api` + `ksp-store-lib`.
|
||||
|
||||
Un unique `ksp-api-lib` monolithique est rejeté.
|
||||
|
||||
## `ksp-program-api` / `ksp-program-lib`
|
||||
|
||||
`ksp-program-api` possède les contrats publics communs de décodage/exécution. Une crate séparée doit pouvoir implémenter et tester ces contrats sans dépendre de `ksp-program-lib`.
|
||||
|
||||
`ksp-program-lib` contient les implémentations officielles intégrées des Program IDs supportés.
|
||||
|
||||
Le decoder vise toute surface techniquement décodable dont la définition est connue. Le statut `deprecated` concerne l'exécution, pas le décodage. 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.
|
||||
|
||||
L'executor expose les opérations techniquement exécutables connues ; une opération obsolète mais encore identifiable/exécutable peut rester implémentée et être marquée `deprecated`. La politique de sécurité appartient à une couche supérieure.
|
||||
|
||||
## `ksp-materializer-api` / `ksp-materializer-lib`
|
||||
|
||||
`ksp-materializer-api` possède les contrats publics/extensibles de matérialisation. Une crate externe doit pouvoir implémenter un materializer contre cette API sans dépendre de `ksp-materializer-lib`.
|
||||
|
||||
`ksp-materializer-lib` contient les materializers officiels intégrés KSP.
|
||||
|
||||
## `ksp-store-api` / `ksp-store-lib`
|
||||
|
||||
`ksp-store-api` possède les contrats backend-agnostic de persistance et d'accès aux données KSP.
|
||||
|
||||
`ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence : configuration/connexion, migrations, repositories, queries et mécanismes backend nécessaires.
|
||||
|
||||
Les applications, workers, jobs et materializers consomment les contrats KSP et ne contournent pas le store pour accéder directement au backend.
|
||||
|
||||
## Notifications de données
|
||||
|
||||
Une notification de donnée décrit la donnée disponible, pas son producteur.
|
||||
|
||||
Le même type de donnée doit utiliser le même contrat de notification qu'elle provienne :
|
||||
|
||||
- de W1 ;
|
||||
- d'un job de backfill ;
|
||||
- d'un import ;
|
||||
- d'une autre source future.
|
||||
|
||||
`ksp-store-api` est le propriétaire candidat des références/événements canoniques indiquant qu'une donnée persistée est disponible, par exemple conceptuellement `RawDataRef` / `RawDataAvailable`.
|
||||
|
||||
Le contrat de notification reste distinct du mécanisme de transport concret : channel in-process, PostgreSQL LISTEN/NOTIFY, IPC, broker ou autre mécanisme futur.
|
||||
|
||||
## Workers
|
||||
|
||||
Les workers sont des services continus/live. Leurs contrats communs appartiennent à :
|
||||
APIs lifecycle retenues :
|
||||
|
||||
```text
|
||||
ksp-worker-api
|
||||
```
|
||||
|
||||
Cette API ne contient aucun contrat de job.
|
||||
|
||||
Une future implémentation commune de gouvernance/contrôle des workers peut vivre dans :
|
||||
|
||||
```text
|
||||
ksp-worker-control-lib
|
||||
```
|
||||
|
||||
W1 reste un worker d'acquisition raw live/quasi-live : configuration, transport, persistance raw, reconfiguration à chaud et notification de disponibilité. Il ne décode pas, ne matérialise pas et ne réalise aucun replay/backfill historique.
|
||||
|
||||
## Jobs
|
||||
|
||||
Les jobs sont des travaux déclenchés à la demande, suivables et terminables. Leurs contrats communs appartiennent à :
|
||||
|
||||
```text
|
||||
ksp-job-api
|
||||
```
|
||||
|
||||
Cette API ne contient aucun contrat de worker.
|
||||
Aucune API commune worker+job n'est prévue.
|
||||
|
||||
Les implémentations concrètes utilisent le préfixe `ksp-job-`.
|
||||
## Execution policy
|
||||
|
||||
Premier candidat retenu :
|
||||
`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é :
|
||||
|
||||
```text
|
||||
ksp-job-backfill
|
||||
ksp-execution-policy-api
|
||||
```
|
||||
|
||||
D'autres jobs pourront être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel existe.
|
||||
Il doit permettre à différents contextes de fournir leurs propres décisions de policy sans modifier `ksp-program-lib` : scenario Devnet, application générale, futur produit trading, etc.
|
||||
|
||||
Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers, même si certaines opérations semblent similaires.
|
||||
Les applications UI sélectionnent/injectent une implémentation réutilisable appropriée ; elles ne doivent pas enfouir une politique complexe directement dans la couche d'interface.
|
||||
|
||||
## Execution orchestration
|
||||
|
||||
`ksp-execution-lib` devient un candidat fort de pipeline/orchestrateur spécialisé pour relier :
|
||||
|
||||
- la préparation/sémantique programme ;
|
||||
- une implémentation de `ksp-execution-policy-api` ;
|
||||
- `ksp-wallet-lib` ;
|
||||
- `ksp-onchain-transport-lib`.
|
||||
|
||||
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`.
|
||||
|
||||
## Transport on-chain
|
||||
|
||||
Aucune `ksp-onchain-transport-api` séparée n'est prévue.
|
||||
|
||||
`ksp-onchain-transport-lib` regroupe les transports/providers on-chain et expose des modèles de sortie homogènes par catégorie de données.
|
||||
|
||||
Il ne dépend pas de `ksp-store-api`.
|
||||
|
||||
Les modèles de transport doivent cependant être conçus pour une conversion explicite et simple vers les modèles raw persistants du store, sans décodage protocolaire.
|
||||
|
||||
## Transport off-chain
|
||||
|
||||
Aucune `ksp-offchain-transport-api` commune n'est prévue.
|
||||
|
||||
La crate est volontairement hétérogène : metadata, prix, quotes, routage et autres ressources externes peuvent avoir des modules/APIs distincts à l'intérieur d'une seule crate afin d'éviter une prolifération de crates artificielles.
|
||||
|
||||
## Wallet
|
||||
|
||||
Aucune `ksp-wallet-api` n'est prévue.
|
||||
|
||||
`ksp-wallet-lib` possède le format wallet KSP et les capacités de lecture/protection/import/export/pubkey/secret/signature nécessaires à ses consommateurs.
|
||||
|
||||
## Store et notifications de données
|
||||
|
||||
`ksp-store-api` reste la frontière backend-agnostic. `ksp-store-lib` contient PostgreSQL comme implémentation de référence.
|
||||
|
||||
Les notifications de données persistées sont normalisées indépendamment de leur producteur. W1, un job de backfill ou un import utilisent le même contrat pour signaler le même type de donnée.
|
||||
|
||||
Le contrat de notification est distinct de son transport concret.
|
||||
|
||||
## Workers
|
||||
|
||||
`ksp-worker-api` est une lifecycle API pour services continus/live.
|
||||
|
||||
`ksp-worker-control-lib` est une implémentation réutilisable de gouvernance pouvant être consommée par les applications manager desktop, une future application globale ou un orchestrateur.
|
||||
|
||||
Workers actuellement retenus :
|
||||
|
||||
```text
|
||||
ksp-worker-raw-retriever
|
||||
ksp-worker-core-processor
|
||||
ksp-worker-generic-materializer
|
||||
ksp-worker-domain-projector
|
||||
```
|
||||
|
||||
Le dernier nom reste provisoire.
|
||||
|
||||
## Jobs
|
||||
|
||||
`ksp-job-api` est une lifecycle API distincte pour travaux déclenchés et terminables.
|
||||
|
||||
`ksp-job-backfill` est retenu pour le backfill historique.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est prévue actuellement. D'autres jobs pourront apparaître pour metadata, quotes ou autres besoins ponctuels.
|
||||
|
||||
## Scénarios
|
||||
|
||||
Les scénarios restent dans des crates spécialisées `ksp-scenario-<domain>-lib`.
|
||||
|
||||
`ksp-scenario-api` n'est pas retenu actuellement : une norme de structure/comportement commune est préférée à un trait Rust obligatoire tant qu'un vrai contrat commun n'a pas émergé.
|
||||
|
||||
Les demos desktop de scénario suivent provisoirement la forme :
|
||||
|
||||
```text
|
||||
ksp-app-scenario-<domain>-<environment>-desk-demo
|
||||
```
|
||||
|
||||
et réutilisent la crate de scénario correspondante.
|
||||
|
||||
## Pipelines
|
||||
|
||||
KSP ne prévoit pas de `ksp-pipeline-lib` monolithique. Lorsqu'un pipeline réutilisable devient nécessaire, il est introduit séparément avec un périmètre concret et borné.
|
||||
Aucun `ksp-pipeline-lib` monolithique.
|
||||
|
||||
## Demos et scénarios
|
||||
|
||||
Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
|
||||
|
||||
Les scénarios sont organisés en crates spécialisées par domaine cohérent, par exemple :
|
||||
|
||||
```text
|
||||
ksp-scenario-memo-lib
|
||||
ksp-scenario-token-lib
|
||||
ksp-scenario-ata-lib
|
||||
ksp-scenario-token-2022-lib
|
||||
ksp-scenario-metadata-lib
|
||||
ksp-scenario-spm-lib
|
||||
```
|
||||
|
||||
Les metadata d'assets/tokens peuvent regrouper Metaplex Token Metadata et Token-2022 Metadata. Solana Program Metadata reste séparé.
|
||||
Des pipelines spécialisés peuvent être ajoutés à la demande. `ksp-execution-lib` est justement étudié comme un pipeline/orchestrateur spécialisé, pas comme une infrastructure universelle.
|
||||
|
||||
271
docs/architecture/004-COMPONENT_INVENTORY.md
Normal file
271
docs/architecture/004-COMPONENT_INVENTORY.md
Normal file
@@ -0,0 +1,271 @@
|
||||
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Inventaire initial des composants KSP
|
||||
|
||||
## Objet
|
||||
|
||||
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.
|
||||
|
||||
## Statuts
|
||||
|
||||
- **Retenu** — composant ou responsabilité considérée nécessaire dans la trajectoire actuelle ;
|
||||
- **Candidat fort** — composant très probable mais dont la frontière exacte doit encore être validée ;
|
||||
- **Futur retenu** — responsabilité acquise mais implémentation différée ;
|
||||
- **À la demande** — ne doit être créé que lorsqu'un premier besoin concret le justifie ;
|
||||
- **Non retenu actuellement** — idée volontairement non créée ; elle peut être réévaluée si l'usage réel change.
|
||||
|
||||
## 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 |
|
||||
|
||||
## APIs séparées retenues
|
||||
|
||||
Les couples suivants ont une justification d'extensibilité suffisante :
|
||||
|
||||
```text
|
||||
ksp-program-api -> ksp-program-lib
|
||||
ksp-materializer-api -> ksp-materializer-lib
|
||||
ksp-store-api -> ksp-store-lib
|
||||
```
|
||||
|
||||
Les APIs lifecycle sont également séparées :
|
||||
|
||||
```text
|
||||
ksp-worker-api -> workers continus
|
||||
ksp-job-api -> jobs terminables
|
||||
```
|
||||
|
||||
Aucune API commune worker+job n'est prévue.
|
||||
|
||||
## Execution policy et orchestration
|
||||
|
||||
### Direction retenue pour étude en `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 :
|
||||
|
||||
```text
|
||||
policy implementation
|
||||
^
|
||||
|
|
||||
ksp-execution-policy-api
|
||||
^
|
||||
|
|
||||
ksp-execution-lib
|
||||
/ | \
|
||||
/ | \
|
||||
program side wallet onchain transport
|
||||
```
|
||||
|
||||
`ksp-program-lib` doit rester propriétaire de la sémantique technique des programmes et de la préparation des opérations, sans posséder la politique de sécurité d'un produit ni le cycle réseau complet.
|
||||
|
||||
`ksp-execution-policy-api` permettrait plusieurs politiques incompatibles mais conformes au même contrat, par exemple :
|
||||
|
||||
- politique permissive et bornée d'un scénario Devnet ;
|
||||
- politique plus stricte d'une future application générale ;
|
||||
- politique spécialisée d'un futur produit de trading.
|
||||
|
||||
Une application UI ne doit pas enfouir cette logique dans ses commandes ou composants. Elle sélectionne/injecte une implémentation réutilisable située dans la crate de scénario ou de domaine appropriée.
|
||||
|
||||
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`.
|
||||
|
||||
## Transport on-chain
|
||||
|
||||
Aucune crate `ksp-onchain-transport-api` n'est prévue.
|
||||
|
||||
`ksp-onchain-transport-lib` peut contenir plusieurs familles hétérogènes :
|
||||
|
||||
- HTTP RPC ;
|
||||
- WebSocket RPC ;
|
||||
- Helius avancé ;
|
||||
- Yellowstone ;
|
||||
- autres providers/transports futurs.
|
||||
|
||||
Les adapters providers doivent toutefois faire sortir de la crate des **modèles de transport homogènes par catégorie de donnée**, afin que les consommateurs n'aient pas à comprendre chaque réponse propriétaire.
|
||||
|
||||
Ces modèles :
|
||||
|
||||
- restent indépendants de `ksp-store-api` ;
|
||||
- conservent les informations raw/provenance nécessaires ;
|
||||
- ne réalisent aucun décodage métier/protocolaire ;
|
||||
- doivent être facilement et explicitement convertibles par `ksp-worker-raw-retriever` vers les modèles raw persistants de `ksp-store-api`.
|
||||
|
||||
Le détail de cette frontière de conversion est reporté à `pre.003/pre.005`.
|
||||
|
||||
## Transport off-chain
|
||||
|
||||
Aucune crate `ksp-offchain-transport-api` ni trait global `OffchainTransport` n'est prévu.
|
||||
|
||||
`ksp-offchain-transport-lib` regroupe volontairement des accès hétérogènes afin d'éviter une explosion de petites crates. Metadata externes, quotes, prix hors blockchain ou routage peuvent conserver des APIs/modules spécialisés à l'intérieur de cette crate sans prétendre partager une abstraction métier commune.
|
||||
|
||||
## Wallet
|
||||
|
||||
Aucune crate `ksp-wallet-api` n'est prévue.
|
||||
|
||||
`ksp-wallet-lib` est propriétaire du format wallet KSP, des opérations de protection/import/export et de l'accès contrôlé aux capacités pubkey/secret/signature nécessaires aux couches supérieures.
|
||||
|
||||
Les applications futures utilisant ce wallet restent des consommateurs de `ksp-wallet-lib`, pas des implémentations alternatives du contrat wallet.
|
||||
|
||||
## Workers
|
||||
|
||||
### `ksp-worker-api`
|
||||
|
||||
`ksp-worker-api` est une **lifecycle API de services continus**.
|
||||
|
||||
Elle pourra porter des contrats communs comme identité, état, health, start/stop/shutdown et événements de lifecycle. Une capacité optionnelle comme la reconfiguration à chaud ne doit devenir universelle que si plusieurs workers la partagent réellement.
|
||||
|
||||
Elle ne contient aucun concept de progression/checkpoint terminal propre aux jobs.
|
||||
|
||||
### `ksp-worker-control-lib`
|
||||
|
||||
`ksp-worker-control-lib` est une implémentation réutilisable de gouvernance au-dessus de `ksp-worker-api`.
|
||||
|
||||
Elle doit pouvoir être consommée par :
|
||||
|
||||
- une application desktop manager spécialisée ;
|
||||
- une future application globale ;
|
||||
- un futur orchestrateur ;
|
||||
- des tools/tests lorsque pertinent.
|
||||
|
||||
Les applications restent des interfaces et ne réimplémentent pas elles-mêmes registre, dispatch start/stop, agrégation d'état ou reconfiguration générique.
|
||||
|
||||
### Workers de processing
|
||||
|
||||
Le modèle initial d'un unique W2 est remplacé par une chaîne de responsabilités plus étroites :
|
||||
|
||||
```text
|
||||
raw persisted
|
||||
|
|
||||
v
|
||||
ksp-worker-core-processor
|
||||
|
|
||||
v
|
||||
canonical Core
|
||||
|
|
||||
v
|
||||
ksp-worker-generic-materializer
|
||||
|
|
||||
v
|
||||
generic materialization/journal
|
||||
|
|
||||
v
|
||||
ksp-worker-domain-projector
|
||||
|
|
||||
v
|
||||
domain projections
|
||||
```
|
||||
|
||||
Le nom `ksp-worker-domain-projector` est explicitement provisoire jusqu'à ce que les contrats de matérialisation spécialisée soient définis.
|
||||
|
||||
## Jobs
|
||||
|
||||
`ksp-job-api` est une **lifecycle API de travaux déclenchés et terminables**.
|
||||
|
||||
Elle peut porter identité, état, progression, cancel, résultat et, lorsque pertinent, pause/resume/checkpoint.
|
||||
|
||||
Aucune `ksp-job-control-lib` n'est prévue actuellement. Le fait que plusieurs jobs implémentent `ksp-job-api` suffit tant qu'aucune duplication concrète de gouvernance ne justifie une bibliothèque commune.
|
||||
|
||||
## Notifications de données
|
||||
|
||||
Les notifications de données restent indépendantes du lifecycle des workers et des jobs.
|
||||
|
||||
Le même type de donnée persistée doit produire le même contrat de notification quelle que soit son origine :
|
||||
|
||||
```text
|
||||
worker live -----\
|
||||
job backfill -----+--> même notification de donnée
|
||||
import -----------/
|
||||
```
|
||||
|
||||
`ksp-store-api` reste le propriétaire candidat de ces références/notifications lorsqu'elles signifient qu'une donnée persistée est disponible.
|
||||
|
||||
Le transport de notification reste distinct du contrat de donnée.
|
||||
|
||||
## Scénarios et demos
|
||||
|
||||
Aucune crate monolithique de scénarios n'est prévue.
|
||||
|
||||
Les scénarios vivent dans des crates spécialisées :
|
||||
|
||||
```text
|
||||
ksp-scenario-memo-lib
|
||||
ksp-scenario-token-lib
|
||||
ksp-scenario-ata-lib
|
||||
ksp-scenario-token-2022-lib
|
||||
ksp-scenario-metadata-lib
|
||||
ksp-scenario-spm-lib
|
||||
...
|
||||
```
|
||||
|
||||
`ksp-scenario-api` n'est pas retenu actuellement. Une **norme de structure/comportement** commune est préférée à un trait Rust susceptible de limiter des scénarios dont les besoins sont différents. Cette décision pourra être revue si les premières implémentations montrent un vrai contrat commun utile.
|
||||
|
||||
Les applications de démonstration correspondantes suivent la forme :
|
||||
|
||||
```text
|
||||
ksp-app-scenario-<domain>-<environment>-desk-demo
|
||||
```
|
||||
|
||||
Exemples :
|
||||
|
||||
```text
|
||||
ksp-app-scenario-memo-devnet-desk-demo
|
||||
ksp-app-scenario-token-2022-devnet-desk-demo
|
||||
ksp-app-scenario-metadata-devnet-desk-demo
|
||||
```
|
||||
|
||||
Chaque application appelle la crate `ksp-scenario-<domain>-lib` correspondante et ne duplique pas son scénario.
|
||||
|
||||
## Pipelines
|
||||
|
||||
`ksp-pipeline-lib` reste rejeté.
|
||||
|
||||
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`
|
||||
|
||||
- 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.
|
||||
@@ -1,101 +1,87 @@
|
||||
<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Plan KSP 0.0.3
|
||||
|
||||
## Mission
|
||||
|
||||
Poursuivre la phase fondatrice sans développement fonctionnel afin de transformer le brainstorming KSP en architecture, règles, nomenclature et plan de développement suffisamment précis pour ouvrir `0.1.x`.
|
||||
Transformer le brainstorming KSP en architecture, règles, inventaire et plan suffisamment précis pour ouvrir la première série fonctionnelle `0.1.x` sans développement fonctionnel prématuré.
|
||||
|
||||
## Décisions structurantes acquises
|
||||
## État courant
|
||||
|
||||
- Les bibliothèques d'implémentation utilisent `ksp-<role>-lib`.
|
||||
- Les crates de contrats publics extensibles utilisent `ksp-<domain>-api`, sans suffixe `-lib`.
|
||||
- Éviter un `ksp-api-lib` monolithique.
|
||||
- Couples API/implémentation retenus : program, materializer, store.
|
||||
- `ksp-store-lib` contient PostgreSQL comme implémentation de référence de `ksp-store-api`.
|
||||
- Les workers continus utilisent `ksp-worker-api`.
|
||||
- Les jobs à la demande utilisent `ksp-job-api`.
|
||||
- Workers et jobs ne partagent pas une abstraction de lifecycle commune.
|
||||
- W1 est strictement raw live/quasi-live et ne fait pas de backfill.
|
||||
- Le backfill historique est un job séparé, candidat `ksp-job-backfill`.
|
||||
- D'autres jobs pourront exister pour metadata, quotes et autres tâches ponctuelles.
|
||||
- Les notifications de données sont normalisées indépendamment de leur producteur ; `ksp-store-api` est le propriétaire candidat des notifications de données persistées.
|
||||
- `ksp-worker-control-lib` est le candidat pour une implémentation commune de contrôle des workers uniquement.
|
||||
- Aucun `ksp-pipeline-lib` monolithique ; pipelines séparés à la demande.
|
||||
- Aucun `ksp-scenarios-lib` monolithique ; scénarios séparés par crates de domaine.
|
||||
- Trading Intelligence précède la couche/application de trading opérationnelle.
|
||||
`pre.001` est considérée stabilisée et commitée comme `v0.0.3-pre.001`.
|
||||
|
||||
## Ligne directrice du développement fonctionnel
|
||||
`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é.
|
||||
|
||||
- `0.1.x` — `ksp-core-lib`, `ksp-logging-lib`, `ksp-config-lib`, `ksp-app-config-desk`.
|
||||
- `0.2.x` — `ksp-onchain-transport-lib`, wallet, `ksp-interface-lib`, `ksp-program-api`, `ksp-program-lib`.
|
||||
- `0.3.x` — `ksp-materializer-api`, `ksp-materializer-lib`, `ksp-store-api`, `ksp-store-lib`, W1, `ksp-worker-api`, `ksp-job-api`, backfill.
|
||||
- `0.4.x` — premières surfaces Core/SPL/metadata, matérialisations, off-chain transport selon besoin, jobs/scénarios/demos spécialisés.
|
||||
- `0.5.x` — Anchor puis protocoles trading par releases bornées.
|
||||
- `0.6.x` — W2, contrôle workers, managers, orchestrateur et application globale.
|
||||
- `0.7.x` — Trading Intelligence.
|
||||
- `0.8.x+` — couche/application trading, extension continue, explorer Solana et explorer/analyse DEX.
|
||||
## Décisions structurantes actuelles
|
||||
|
||||
## Prévision souple des prereleases 0.0.3
|
||||
- `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.
|
||||
- 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).
|
||||
- `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.
|
||||
|
||||
### `pre.001` — Base de planification
|
||||
## Prévision souple des prereleases restantes
|
||||
|
||||
Considérée stabilisée après les fixes de cadrage.
|
||||
### `pre.002` — Inventaire initial des composants
|
||||
|
||||
### `pre.002` — Domaines et crates candidates
|
||||
- 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`.
|
||||
|
||||
- inventorier les domaines fonctionnels ;
|
||||
- fixer les couples `*-api` / `*-lib` réellement justifiés ;
|
||||
- définir workers vs jobs ;
|
||||
- définir les responsabilités des notifications de données ;
|
||||
- inventorier les scénarios/pipelines spécialisés ;
|
||||
- définir pour chaque crate candidate responsabilité, niveau, entrées/sorties et consommateurs ;
|
||||
- mettre à jour le brouillon de prompt `0.1.x`.
|
||||
### `pre.003` — Graphe de dépendances et correction de l'inventaire
|
||||
|
||||
### `pre.003` — Graphe de dépendances
|
||||
- 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.
|
||||
|
||||
- construire le graphe de dépendances autorisées/interdites ;
|
||||
- identifier les propriétaires des dépendances Solana externes ;
|
||||
- vérifier les risques de cycles ;
|
||||
- positionner précisément les crates `*-api` ;
|
||||
- préciser les dépendances autorisées de `ksp-program-api`, `ksp-materializer-api`, `ksp-store-api`, `ksp-worker-api` et `ksp-job-api`.
|
||||
### `pre.004` — Programmes, wire et exécution
|
||||
|
||||
### `pre.004` — Programmes, décodage 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.
|
||||
|
||||
- détailler `ksp-program-api` et `ksp-program-lib` ;
|
||||
- définir les interfaces wire et leur source de vérité ;
|
||||
- cadrer les tests de conformité ;
|
||||
- définir le niveau supérieur propriétaire de la sécurité d'exécution ;
|
||||
- traiter Metaplex/ElGamal comme exemples architecturaux sans développement fonctionnel.
|
||||
### `pre.005` — Données, store et acquisitions
|
||||
|
||||
### `pre.005` — Données, storage et acquisitions
|
||||
- détailler materializer/store ;
|
||||
- finaliser les modèles raw et notifications ;
|
||||
- détailler W1 et backfill ;
|
||||
- cadrer les trois workers de processing futurs ;
|
||||
- revisiter les niveaux durables/replay.
|
||||
|
||||
- détailler `ksp-materializer-api` / `ksp-materializer-lib` ;
|
||||
- détailler `ksp-store-api` / `ksp-store-lib` ;
|
||||
- finaliser W1, `ksp-worker-api` et ses notifications de données ;
|
||||
- détailler `ksp-job-api` et le backfill ;
|
||||
- cadrer W2 sans l'implémenter ;
|
||||
- définir les frontières backend et replay/reconstruction.
|
||||
### `pre.006` — Applications, workers, jobs, scenarios et pipelines spécialisés
|
||||
|
||||
### `pre.006` — Applications, workers, jobs, demos et scénarios
|
||||
- formaliser les apps spécialisées ;
|
||||
- détailler `ksp-worker-control-lib` ;
|
||||
- définir la norme des crates scénario et leurs apps demo ;
|
||||
- inventorier les pipelines spécialisés réellement nécessaires.
|
||||
|
||||
- formaliser config/store/wallet apps ;
|
||||
- finaliser la nomenclature réseau/environnement ;
|
||||
- détailler les crates de scénarios spécialisées ;
|
||||
- détailler managers workers/jobs et trajectoire vers l'orchestrateur ;
|
||||
- inventorier les pipelines spécialisés nécessaires sans crate pipeline monolithique.
|
||||
### `pre.007` — Plan des premières releases fonctionnelles
|
||||
|
||||
### `pre.007` — Plan de développement et contrôle de charge
|
||||
|
||||
- affiner le roadmap fonctionnel `0.1.x+` ;
|
||||
- détailler le premier plan `0.1.x` ;
|
||||
- transformer le brouillon de prompt en quasi-version finale ;
|
||||
- vérifier et redécouper la charge de la session suivante si nécessaire.
|
||||
- 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.
|
||||
|
||||
### `pre.008` — Clôture fondatrice
|
||||
|
||||
- vérifier la cohérence règles/architecture/plans ;
|
||||
- mettre à jour la documentation finale ;
|
||||
- nettoyer/archiver les éléments temporaires ;
|
||||
- finaliser le prompt de reprise `0.1.x`.
|
||||
- validations finales de cohérence ;
|
||||
- documentation/nettoyage/archivage ;
|
||||
- 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.
|
||||
|
||||
@@ -1,203 +1,70 @@
|
||||
<!-- file: docs/rules/PROMPT_STRUCTURE.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Structure des prompts KSP
|
||||
|
||||
## Portée
|
||||
|
||||
Ce document définit le contrat normatif des prompts de reprise KSP, leur cycle de vie et les règles de dimensionnement des sessions/prereleases qu'ils préparent.
|
||||
Ce document définit le contrat normatif des prompts de reprise KSP, leur cycle de vie et les règles de dimensionnement des releases/sessions qu'ils préparent.
|
||||
|
||||
Les prompts eux-mêmes sont conservés sous `prompts/`.
|
||||
## Série, release concrète et session
|
||||
|
||||
## Objectif
|
||||
Une notation de série telle que `0.1.x` regroupe des fonctionnalités apparentées. Elle n'est pas une unité de session et n'a pas à être réalisable en une seule session.
|
||||
|
||||
Un prompt doit permettre de reprendre le travail sans reconstituer manuellement :
|
||||
Exemple : `0.1.x` peut regrouper plusieurs releases concrètes comme `0.1.1`, `0.1.2`, `0.1.3`, chacune avec son propre cycle de prereleases et, en principe, sa propre session de travail principale.
|
||||
|
||||
- la mission de la phase ;
|
||||
- la base Git/version ;
|
||||
- l'état validé à préserver ;
|
||||
- les règles applicables ;
|
||||
- l'architecture déjà décidée ;
|
||||
- les questions encore ouvertes ;
|
||||
- les sources externes normatives lorsqu'elles existent ;
|
||||
- le plan souple ;
|
||||
- le mode de livraison ;
|
||||
- les validations et critères de sortie.
|
||||
Le contrôle de charge s'applique donc d'abord à **la release concrète préparée** et à ses prereleases, pas à toute la série fonctionnelle.
|
||||
|
||||
Le prompt ne remplace jamais les sources de vérité du dépôt.
|
||||
|
||||
## Cycle de vie
|
||||
|
||||
Un prompt de prochaine grande phase est créé dès que sa direction devient suffisamment claire.
|
||||
|
||||
Il passe par trois états conceptuels :
|
||||
|
||||
1. **Brouillon** — créé tôt et volontairement incomplet ;
|
||||
2. **Quasi-final** — mis à jour lorsque les frontières, crates, dépendances et objectifs sont suffisamment stabilisés ;
|
||||
3. **Final** — vérifié pendant la phase documentaire de clôture et prêt à être utilisé comme point de départ de la session/version suivante.
|
||||
|
||||
Le prompt de la phase suivante doit être maintenu pendant la phase courante lorsque de nouvelles décisions changent matériellement son futur démarrage.
|
||||
|
||||
## Première et dernière prerelease d'une version
|
||||
## Cycle d'une release concrète
|
||||
|
||||
Sauf raison explicitement documentée :
|
||||
|
||||
- la première prerelease (`pre.001`) est consacrée au brainstorming, à l'audit lorsque nécessaire, à la planification, aux décisions de périmètre et au découpage souple des prereleases suivantes ;
|
||||
- la dernière prerelease est consacrée à la validation finale, à la documentation, au nettoyage/archivage nécessaire, à la synchronisation des documents de release et à la finalisation du prompt de la session/version suivante.
|
||||
|
||||
Le développement fonctionnel significatif ne doit pas précéder le cadrage suffisant de `pre.001`.
|
||||
- `pre.001` = brainstorming/audit si nécessaire + planification + découpage de la release ;
|
||||
- les prereleases intermédiaires = tranches bornées de développement/validation ;
|
||||
- la dernière prerelease = validation finale + documentation + nettoyage/archivage + préparation du prompt/release suivante.
|
||||
|
||||
## Dimensionnement des prereleases
|
||||
|
||||
Pendant l'élaboration du plan de `pre.001`, les prereleases de travail situées après `pre.001` et avant la prerelease finale de clôture doivent être conçues comme des tranches bornées.
|
||||
Lors de `pre.001`, une prerelease intermédiaire estimée à plus d'environ **15 à 20 minutes de travail effectif de session** doit être scindée.
|
||||
|
||||
Lors de la planification, une tranche dont la charge estimée paraît dépasser approximativement **15 à 20 minutes de travail effectif de session** doit être scindée en plusieurs prereleases ou sous-objectifs livrables séparément.
|
||||
Cette durée est un budget de planification et non une promesse d'exécution.
|
||||
|
||||
Cette durée est un budget de planification, pas une promesse de temps d'exécution. Elle sert à empêcher les tranches trop larges, difficiles à valider ou à corriger.
|
||||
Si la complexité réelle augmente, la tranche est redécoupée plutôt que surchargée.
|
||||
|
||||
Si la complexité réelle découverte en cours de travail dépasse l'estimation, la tranche doit être redécoupée plutôt que surchargée.
|
||||
## Dimensionnement d'une release/session
|
||||
|
||||
## Dimensionnement d'une session ou d'une version
|
||||
Avant de finaliser le prompt d'une release concrète, vérifier que son plan complet est compatible avec une session de qualité.
|
||||
|
||||
Avant de finaliser le prompt de la session suivante, il faut évaluer la charge totale produite par le plan prévu.
|
||||
Si une release concrète paraît trop lourde, la scinder en plusieurs releases de la même série lorsque les fonctions restent du même groupe, ou changer de série si une frontière fonctionnelle différente le justifie.
|
||||
|
||||
Si un prompt risque de générer trop de prereleases, trop de fichiers, trop de décisions ou un contexte trop lourd pour une seule session de qualité, le périmètre doit être découpé :
|
||||
Exemple : si `0.1.1` devient trop large, créer `0.1.2` plutôt que forcer tout `0.1.x` dans une seule session.
|
||||
|
||||
- en plusieurs sessions conservant éventuellement la même série/version lorsque la continuité fonctionnelle le justifie ;
|
||||
- et/ou en plusieurs versions lorsque la séparation correspond à une frontière fonctionnelle plus propre.
|
||||
|
||||
Exemple : si une version prévue pour introduire decoder + executor devient manifestement trop lourde après planification, la continuité du roadmap est conservée mais le travail peut être réparti sur plusieurs sessions ou versions.
|
||||
|
||||
La qualité du contexte, la testabilité et la cohérence architecturale priment sur le maintien artificiel d'un découpage de versions imaginé plus tôt.
|
||||
Une série complète peut naturellement s'étendre sur de nombreuses sessions.
|
||||
|
||||
## Structure recommandée d'un prompt
|
||||
|
||||
### 1. Identité de la phase
|
||||
|
||||
Indiquer :
|
||||
|
||||
- version ou série visée ;
|
||||
- titre court ;
|
||||
- nature de la session : brainstorming, planification, développement, audit, validation, clôture, etc.
|
||||
|
||||
### 2. Mission
|
||||
|
||||
Décrire l'état concret à atteindre pendant la phase.
|
||||
|
||||
La mission ne doit pas être une simple liste de fichiers à modifier.
|
||||
|
||||
### 3. Base requise
|
||||
|
||||
Indiquer :
|
||||
|
||||
- version/tag/commit de départ ;
|
||||
- état attendu du workspace ;
|
||||
- fichiers/documents fondamentaux déjà présents.
|
||||
|
||||
### 4. État validé à préserver
|
||||
|
||||
Lister les éléments déjà validés qui ne doivent pas régresser pendant la nouvelle phase, par exemple :
|
||||
|
||||
- APIs déjà stabilisées ;
|
||||
- comportements fonctionnels validés ;
|
||||
- tests/scénarios connus comme passants ;
|
||||
- décisions gelées ou fortement contraintes ;
|
||||
- problèmes explicitement reportés qui ne doivent pas être rouverts sans raison.
|
||||
|
||||
Cette section est distincte de la simple base Git/version.
|
||||
|
||||
### 5. Sources de vérité internes à relire
|
||||
|
||||
Lister explicitement les documents nécessaires, en priorité :
|
||||
|
||||
- `RULES.md` et règles spécialisées pertinentes ;
|
||||
- `ROADMAP.md` ;
|
||||
- plan de version actif ;
|
||||
- architecture concernée ;
|
||||
- `docs/IDEAS.md` lorsqu'une question ouverte est pertinente ;
|
||||
- dernier delta/release utile.
|
||||
|
||||
Le prompt doit renvoyer aux sources de vérité au lieu de les recopier intégralement.
|
||||
|
||||
### 6. Sources externes normatives
|
||||
|
||||
Lorsqu'une phase concerne un protocole, programme, standard ou API externe, lister les sources qui font autorité :
|
||||
|
||||
- dépôt upstream officiel ;
|
||||
- documentation officielle ;
|
||||
- IDL/schema officiel ;
|
||||
- Program ID ;
|
||||
- format wire ;
|
||||
- spécification normative ;
|
||||
- autre source externe explicitement retenue.
|
||||
|
||||
Une copie historique locale ne doit pas être traitée comme source de vérité actuelle lorsque la phase exige une vérification upstream.
|
||||
|
||||
### 7. Décisions acquises
|
||||
|
||||
Résumer uniquement les décisions indispensables pour éviter une mauvaise direction au démarrage.
|
||||
|
||||
### 8. Objectifs et livrables
|
||||
|
||||
Lister les objectifs principaux et les artefacts attendus.
|
||||
|
||||
### 9. Hors périmètre
|
||||
|
||||
Indiquer ce qui ne doit explicitement pas être ouvert pendant la phase.
|
||||
|
||||
### 10. Méthode de travail
|
||||
|
||||
Rappeler la séquence KSP applicable :
|
||||
|
||||
1. brainstorming ;
|
||||
2. planification ;
|
||||
3. développement lorsque la phase est fonctionnelle ;
|
||||
4. tests/validations ;
|
||||
5. documentation finale ;
|
||||
6. mise à jour/préparation du prompt suivant.
|
||||
|
||||
Une phase fondatrice/documentaire adapte la partie développement à son objet.
|
||||
|
||||
### 11. Versionnement et deltas
|
||||
|
||||
Rappeler :
|
||||
|
||||
- version Cargo attendue ;
|
||||
- format du delta ;
|
||||
- règle des fixes techniques/documentaires ;
|
||||
- politique de commits de la phase ;
|
||||
- règle de découpage des livraisons trop volumineuses.
|
||||
|
||||
### 12. Contraintes techniques spécifiques
|
||||
|
||||
Lister uniquement les contraintes importantes pour cette phase : dépendances, environnements, sécurité, API publique, stockage, transport, etc.
|
||||
|
||||
### 13. Plan initial souple
|
||||
|
||||
Pour un `pre.001`, fournir la prévision souple des prereleases ou étapes principales.
|
||||
|
||||
Chaque tranche intermédiaire doit respecter le budget de complexité défini plus haut et être redécoupée si nécessaire.
|
||||
|
||||
### 14. Validations attendues
|
||||
|
||||
Indiquer les commandes/tests/audits pertinents et interdire de déclarer une validation non exécutée.
|
||||
|
||||
### 15. Critères de sortie
|
||||
|
||||
Décrire les conditions nécessaires pour considérer la phase terminée.
|
||||
|
||||
### 16. Préparation de la suite
|
||||
|
||||
Indiquer quel document/prompt doit être produit ou mis à jour avant la clôture.
|
||||
|
||||
Avant finalisation de ce prompt suivant, appliquer obligatoirement le contrôle de dimensionnement de session/version.
|
||||
1. Identité de la série et de la release concrète visée ;
|
||||
2. Mission ;
|
||||
3. Base requise ;
|
||||
4. État validé à préserver ;
|
||||
5. Sources de vérité internes ;
|
||||
6. Sources externes normatives ;
|
||||
7. Décisions acquises ;
|
||||
8. Objectifs et livrables ;
|
||||
9. Hors périmètre ;
|
||||
10. Méthode de travail ;
|
||||
11. Versionnement/deltas/commits ;
|
||||
12. Contraintes techniques spécifiques ;
|
||||
13. Plan initial souple et prereleases bornées ;
|
||||
14. Validations attendues ;
|
||||
15. Critères de sortie ;
|
||||
16. Préparation de la release/session suivante.
|
||||
|
||||
## Règles de rédaction
|
||||
|
||||
- Le prompt est précis mais évite de dupliquer plusieurs pages déjà présentes dans les documents canoniques.
|
||||
- Une règle normative appartient d'abord à `docs/rules/`, pas seulement au prompt.
|
||||
- Une décision architecturale durable appartient à `docs/architecture/`, pas seulement au prompt.
|
||||
- Le prompt référence les sources canoniques au lieu de recopier inutilement leur contenu.
|
||||
- Une règle normative appartient à `docs/rules/`.
|
||||
- Une décision durable appartient à `docs/architecture/`.
|
||||
- Une idée non décidée appartient à `docs/IDEAS.md`.
|
||||
- Le prompt doit signaler les questions ouvertes plutôt que les résoudre arbitrairement.
|
||||
- Les chemins et versions mentionnés doivent être cohérents avec le dépôt au moment de la finalisation.
|
||||
- Un prompt final ne doit pas préparer une session manifestement surdimensionnée.
|
||||
- Un prompt doit signaler les questions ouvertes plutôt que les résoudre arbitrairement.
|
||||
- Une release concrète manifestement surdimensionnée doit être redécoupée avant ouverture de sa session principale.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_KSP.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Règles spécifiques à KSP
|
||||
|
||||
@@ -13,6 +13,7 @@
|
||||
- **KSP-NAME-006** — Un job ponctuel/historique/terminable se nomme `ksp-job-<role>`.
|
||||
- **KSP-NAME-007** — Une démonstration se termine par `-demo`.
|
||||
- **KSP-NAME-008** — Les crates Rust sont placées directement sous `crates/`.
|
||||
- **KSP-NAME-009** — Une application desktop de scénario spécialisée suit la forme `ksp-app-scenario-<domain>-<environment>-desk-demo` lorsque l'environnement est imposé.
|
||||
|
||||
## Architecture et APIs
|
||||
|
||||
@@ -22,8 +23,9 @@
|
||||
- **KSP-API-004** — Un contrat public extensible doit pouvoir être implémenté depuis une crate séparée du workspace principal lorsque cela est techniquement pertinent.
|
||||
- **KSP-API-005** — Les signatures des contrats publics utilisent en priorité des types publics KSP et les primitives externes explicitement admises ; elles ne doivent pas imposer des détails internes instables.
|
||||
- **KSP-API-006** — `ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence derrière `ksp-store-api`.
|
||||
- **KSP-API-007** — Une crate `*-api` n'est créée que lorsqu'un vrai besoin d'extension, backend ou lifecycle le justifie ; la symétrie de nommage n'est jamais une justification suffisante.
|
||||
|
||||
## Programmes
|
||||
## Programmes et exécution
|
||||
|
||||
- **KSP-PROGRAM-001** — Les contrats decoder/executor appartiennent à `ksp-program-api`; les implémentations officielles intégrées appartiennent à `ksp-program-lib`.
|
||||
- **KSP-PROGRAM-002** — Le decoder vise toute surface techniquement décodable dont la définition est connue, y compris les formats anciens, obsolètes ou expérimentaux encore distinguables.
|
||||
@@ -31,24 +33,43 @@
|
||||
- **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-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.
|
||||
|
||||
## Transports
|
||||
|
||||
- **KSP-TRANSPORT-001** — KSP ne crée pas de `ksp-onchain-transport-api` séparée dans l'architecture actuelle.
|
||||
- **KSP-TRANSPORT-002** — `ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api`.
|
||||
- **KSP-TRANSPORT-003** — Les providers on-chain normalisent leurs sorties dans des modèles de transport homogènes par catégorie de données avant exposition aux consommateurs.
|
||||
- **KSP-TRANSPORT-004** — Les modèles de transport restent sans décodage métier/protocolaire et doivent être explicitement/facilement convertibles vers les modèles raw persistants de `ksp-store-api` par la couche d'acquisition.
|
||||
- **KSP-TRANSPORT-005** — KSP ne crée pas de `ksp-offchain-transport-api` globale ni de trait universel artificiel pour des domaines off-chain hétérogènes.
|
||||
|
||||
## Wallet
|
||||
|
||||
- **KSP-WALLET-001** — KSP ne crée pas de `ksp-wallet-api` dans l'architecture actuelle ; `ksp-wallet-lib` possède le format wallet KSP et ses capacités de lecture/protection/import/export/pubkey/secret/signature.
|
||||
|
||||
## Workers
|
||||
|
||||
- **KSP-WORKER-001** — Un worker représente un service continu/live ; il est distinct d'un job.
|
||||
- **KSP-WORKER-002** — Les contrats communs des workers appartiennent à `ksp-worker-api` et ne contiennent aucun contrat propre aux jobs.
|
||||
- **KSP-WORKER-003** — `ksp-worker-control-lib` est le candidat d'implémentation commune de gouvernance/contrôle des workers lorsque plusieurs consommateurs le justifient.
|
||||
- **KSP-WORKER-004** — W1 est un worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique.
|
||||
- **KSP-WORKER-005** — W1 persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
|
||||
- **KSP-WORKER-006** — W1 doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
|
||||
- **KSP-WORKER-003** — `ksp-worker-api` est principalement une lifecycle API de services continus : identité, état, health, démarrage/arrêt et événements communs ; les capacités optionnelles ne deviennent universelles que si plusieurs workers les partagent réellement.
|
||||
- **KSP-WORKER-004** — `ksp-worker-control-lib` est une implémentation commune de gouvernance/contrôle réutilisable par managers desktop, future application globale et orchestrateur ; les apps ne réimplémentent pas cette gouvernance.
|
||||
- **KSP-WORKER-005** — `ksp-worker-raw-retriever` est le worker d'acquisition raw live/quasi-live. Il ne décode pas, ne matérialise pas et ne réalise pas de replay/backfill historique.
|
||||
- **KSP-WORKER-006** — `ksp-worker-raw-retriever` persiste les données raw puis notifie leur disponibilité selon les contrats de données normalisés.
|
||||
- **KSP-WORKER-007** — `ksp-worker-raw-retriever` doit pouvoir faire évoluer à chaud les listeners et la sélection des données qu'il rapatrie/stocke.
|
||||
- **KSP-WORKER-008** — Les workers de processing actuellement retenus sont `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector`; le dernier nom reste provisoire.
|
||||
|
||||
## Jobs
|
||||
|
||||
- **KSP-JOB-001** — Un job représente un travail déclenché à la demande, suivable et terminable ; il est distinct d'un worker continu.
|
||||
- **KSP-JOB-002** — Les contrats communs des jobs appartiennent à `ksp-job-api` et ne contiennent aucun contrat propre aux workers.
|
||||
- **KSP-JOB-003** — Les implémentations concrètes utilisent le préfixe `ksp-job-`.
|
||||
- **KSP-JOB-004** — `ksp-job-backfill` est le candidat retenu pour le backfill historique ; il ne doit pas être implémenté comme un mode W1.
|
||||
- **KSP-JOB-005** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
|
||||
- **KSP-JOB-006** — Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers.
|
||||
- **KSP-JOB-003** — `ksp-job-api` est principalement une lifecycle API de travaux terminables : identité, état, progression, annulation, résultat et capacités de reprise lorsqu'elles sont pertinentes.
|
||||
- **KSP-JOB-004** — Les implémentations concrètes utilisent le préfixe `ksp-job-`.
|
||||
- **KSP-JOB-005** — `ksp-job-backfill` est retenu pour le backfill historique ; il ne doit pas être implémenté comme un mode du worker raw.
|
||||
- **KSP-JOB-006** — D'autres jobs peuvent être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel le justifie.
|
||||
- **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.
|
||||
|
||||
## Notifications de données
|
||||
|
||||
@@ -60,14 +81,16 @@
|
||||
## Pipelines et scénarios
|
||||
|
||||
- **KSP-PIPE-001** — KSP ne crée pas de `ksp-pipeline-lib` monolithique. Les pipelines sont introduits séparément à la demande selon leur responsabilité réelle.
|
||||
- **KSP-DEMO-001** — Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
|
||||
- **KSP-DEMO-002** — Les scénarios sont séparés en crates `ksp-scenario-<domain>-lib` par responsabilité fonctionnelle cohérente.
|
||||
- **KSP-DEMO-003** — Memo, SPL Token classique, ATA et Token-2022 restent dans des crates/scénarios séparés.
|
||||
- **KSP-DEMO-004** — Une famille metadata d'assets/tokens peut regrouper Metaplex Token Metadata et Token-2022 Metadata ; Solana Program Metadata reste séparé.
|
||||
- **KSP-DEMO-005** — Lorsqu'un scénario réutilisable existe dans KSP, l'application demo le consomme et ne réimplémente pas le workflow.
|
||||
- **KSP-SCENARIO-001** — Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
|
||||
- **KSP-SCENARIO-002** — Les scénarios sont séparés en crates `ksp-scenario-<domain>-lib` par responsabilité fonctionnelle cohérente.
|
||||
- **KSP-SCENARIO-003** — `ksp-scenario-api` n'est pas retenu actuellement ; KSP privilégie d'abord une norme documentaire/structurelle commune qui ne limite pas les contrats spécifiques des scénarios.
|
||||
- **KSP-SCENARIO-004** — Memo, SPL Token classique, ATA et Token-2022 restent dans des crates/scénarios séparés.
|
||||
- **KSP-SCENARIO-005** — Une famille metadata d'assets/tokens peut regrouper Metaplex Token Metadata et Token-2022 Metadata ; Solana Program Metadata reste séparé.
|
||||
- **KSP-SCENARIO-006** — Lorsqu'un scénario réutilisable existe dans KSP, l'application demo le consomme et ne réimplémente pas le workflow.
|
||||
|
||||
## Applications
|
||||
|
||||
- **KSP-APP-001** — Une application KSP est une interface et une couche de composition. Elle ne réimplémente pas une opération appartenant conceptuellement à un composant KSP réutilisable inférieur.
|
||||
- **KSP-APP-002** — Les applications/demos ne dépendent pas directement de crates Solana/protocoles externes.
|
||||
- **KSP-APP-003** — Les applications/demos peuvent réaliser les opérations strictement liées à l'interface, mais pas la logique métier/protocolaire réutilisable.
|
||||
- **KSP-APP-004** — Une demo scenario desktop consomme la crate `ksp-scenario-<domain>-lib` correspondante ; elle suit la convention `ksp-app-scenario-<domain>-<environment>-desk-demo` lorsque l'environnement est imposé.
|
||||
|
||||
Reference in New Issue
Block a user