v0.0.3-pre.002
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user