6.1 KiB
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, le graphe autorisé/interdit dans 005-DEPENDENCY_GRAPH.md et les contrats Wire/Program dans 006-WIRE_AND_PROGRAM.md.
Convention API / implémentation
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP peut séparer :
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.
Cette séparation n'est pas automatique. Elle est utilisée lorsqu'une vraie frontière d'extension/backend/lifecycle la justifie.
Couples retenus :
ksp-program-api / ksp-program-lib
ksp-materializer-api / ksp-materializer-lib
ksp-store-api / ksp-store-lib
APIs lifecycle retenues :
ksp-worker-api
ksp-job-api
Aucune API commune worker+job n'est prévue.
Execution policy
ksp-program-lib ne possède pas la politique de sécurité/autorisation d'un produit.
Le contrat public séparé suivant est retenu :
ksp-execution-policy-api
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.
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 est retenu comme 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.
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
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 :
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 :
ksp-app-scenario-<domain>-<environment>-desk-demo
et réutilisent la crate de scénario correspondante.
Pipelines
Aucun ksp-pipeline-lib monolithique.
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.