11 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, Wire/Program dans 006-WIRE_AND_PROGRAM.md Execution/Policy dans 007-EXECUTION_AND_POLICY.md, Data/Materialization/Store dans 008-DATA_MATERIALIZATION_AND_STORE.md Acquisition/Workers/Jobs dans 009-ACQUISITION_WORKERS_AND_JOBS.md et Apps/Services/Scenarios/Control dans 010-APPS_SERVICES_SCENARIOS_AND_CONTROL.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-execution-policy-api est un contrat public de décision séparé de ksp-program-lib, du wallet, du transport et de l'UI.
Une exécution réelle via ksp-execution-lib reçoit explicitement une policy ; aucun fallback permissif implicite n'est prévu.
La policy peut être évaluée à plusieurs checkpoints afin d'intégrer des informations obtenues pendant le cycle, notamment le résultat de simulation.
Une policy peut autoriser, refuser ou imposer des requirements ; elle ne réalise pas elle-même la simulation, la signature, le réseau ou une interaction Tauri.
Les implémentations appartiennent aux crates de contexte appropriées : scenario Devnet, future bibliothèque d'application générale, future policy trading, etc.
Aucune ksp-execution-policy-lib générique n'est prévue sans logique réellement commune.
Execution orchestration
ksp-execution-lib consomme fondamentalement PreparedProgramExecution conforme à ksp-program-api et ne dépend pas de ksp-program-lib.
Il orchestre :
- policy checkpoints ;
- assemblage message/transaction ;
- simulation via
ksp-onchain-transport-lib; - résolution des signers et signature via
ksp-wallet-lib; - submission ;
- confirmation ;
- retry d'exécution lorsque celui-ci change le lifecycle ;
- suspension/reprise lorsqu'une approbation externe est requise.
Le wallet et le provider/réseau sont sélectionnés/fournis par la composition supérieure ; ksp-execution-lib les utilise sans définir une policy de sélection implicite.
Le retry d'un appel réseau identique reste une responsabilité transport, distincte du retry d'exécution nécessitant reconstruction/resimulation/resignature.
ksp-execution-lib ne persiste pas automatiquement son résultat et ne dépend pas du store.
Logging
ksp-logging-lib est la façade KSP unique pour le logging/tracing runtime. Elle importe/initialise directement tracing, tracing-appender et tracing-subscriber et peut dépendre de ksp-core-lib pour Error / Result.
Les crates comportementales KSP utilisent sa façade pour leurs événements error, warn, info, debug, trace et pour leurs spans sync/async. Elles n'émettent pas leurs propres logs via une dépendance directe à la stack tracing.
Chaque émission KSP indique un target correspondant au nom Cargo de la crate propriétaire ; domain, component et les autres champs structurés décrivent les subdivisions fonctionnelles sans multiplier les targets.
Le subscriber KSP rend les targets tiers silencieux par défaut. Lorsqu'une information provenant d'une dépendance externe est nécessaire, la crate KSP qui possède l'opération la réémet explicitement sous son propre target ; Logging ne renomme pas les événements tiers.
Logging possède ses LoggingSettings, ses writers/guards et son lifecycle. Le subscriber global est installé une fois, puis la configuration peut être rechargée à chaud via la façade KSP sans dépendance vers Config.
ksp-core-lib n'a pas de dépendance logging requise. Les crates *-api purement déclaratives restent sans logging par défaut.
Une application Tauri peut exceptionnellement avoir une dépendance/framework tracing imposée par un plugin, sans définir une politique parallèle à ksp-logging-lib; les événements KSP restent émis via la façade KSP.
Frontière materializer / store
Les niveaux durables utilisent D1 Raw, D2 Core canonique, D3 journal de matérialisation générique et D4 projections spécialisées.
ksp-materializer-api peut dépendre de ksp-program-api pour consommer des contrats Core ouverts. Il doit pouvoir distinguer conceptuellement une matérialisation générique D2 -> D3 et une projection spécialisée D3 -> D4.
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/jobs de processing convertissent explicitement entre modèles runtime et modèles persistants.
D3 est un journal durable obligatoire ; D4 reste plus évolutif. Cette séparation é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, un import ou un replay utilisent le même contrat pour signaler le même type de donnée.
Une notification est seulement un signal de réveil : le Store et les marqueurs d'idempotence/backlog restent la source de vérité. La publication suit l'ordre persist -> commit -> notify.
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 d'abord par les applications manager spécialisées, puis éventuellement par un futur orchestrateur ou une future application globale.
Workers retenus :
ksp-worker-raw-retriever
ksp-worker-core-processor
ksp-worker-generic-materializer
ksp-worker-domain-projector
Le dernier nom reste provisoire.
Chaque worker doit pouvoir fonctionner comme service/processus indépendant afin d'être arrêté, redémarré ou mis à jour sans imposer l'arrêt des autres. La direction de packaging préférée est un package ksp-worker-* avec cible bibliothèque réutilisable et binaire autonome mince.
Les workers de processing utilisent le Store comme source de vérité du backlog, peuvent être réveillés par notification, et doivent pouvoir reprendre après crash. Le raw retriever possède en plus une capacité de hot reconfiguration de sa sélection d'acquisition.
Jobs
ksp-job-api est une lifecycle API distincte pour travaux déclenchés et terminables.
Jobs de données retenus :
ksp-job-backfill
ksp-job-replay-core
ksp-job-replay-generic-materialization
ksp-job-replay-domain-projection
Les trois jobs de replay correspondent exactement aux frontières D1 -> D2, D2 -> D3 et D3 -> D4.
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 : docs/rules/SCENARIO_CONVENTION.md porte la norme commune tant qu'un vrai contrat Rust réutilisable 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.
Applications, services et control plane
Les applications spécialisées sont développées avant toute application globale.
Les apps restent des interfaces/compositions et ne réimplémentent pas les workflows des bibliothèques/services sous-jacents.
Les workers sont des services autonomes et ne communiquent pas directement leurs données entre eux. D1–D4 constituent le data plane ; ksp-worker-api, ksp-worker-control-lib, ksp-job-api et le futur IPC constituent le control plane.
Aucun ksp-ipc-api générique ni ksp-orchestrator-lib n'est retenu comme crate actuelle.
Une future application globale est conservée comme idée produit, pas comme tâche du roadmap présent.
Pipelines
Aucun ksp-pipeline-lib monolithique.
Quatre pipelines spécialisés sont maintenant retenus parce qu'ils évitent de dupliquer une même frontière entre worker live et job :
ksp-pipeline-raw-ingestion-lib
ksp-pipeline-core-processing-lib
ksp-pipeline-generic-materialization-lib
ksp-pipeline-domain-projection-lib
Ils dépendent des APIs de domaine nécessaires, pas des implémentations officielles ksp-store-lib, ksp-program-lib ou ksp-materializer-lib. Les workers/jobs réalisent cette composition.