197 lines
8.9 KiB
Markdown
197 lines
8.9 KiB
Markdown
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
|
<!-- version: 9 -->
|
|
|
|
# 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), le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md), Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) Execution/Policy dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md), Data/Materialization/Store dans [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) et Acquisition/Workers/Jobs dans [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md).
|
|
|
|
## Convention API / implémentation
|
|
|
|
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`.
|
|
|
|
Cette séparation n'est pas automatique. Elle est utilisée lorsqu'une vraie frontière d'extension/backend/lifecycle la justifie.
|
|
|
|
Couples retenus :
|
|
|
|
```text
|
|
ksp-program-api / ksp-program-lib
|
|
ksp-materializer-api / ksp-materializer-lib
|
|
ksp-store-api / ksp-store-lib
|
|
```
|
|
|
|
APIs lifecycle retenues :
|
|
|
|
```text
|
|
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 peuvent dépendre directement de `ksp-logging-lib` et utilisent sa façade pour `error`, `warn`, `info`, `debug` et `trace` avec target/domain/champs structurés selon l'API finale.
|
|
|
|
`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`.
|
|
|
|
## 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 par les applications manager desktop, une future application globale ou un orchestrateur.
|
|
|
|
Workers retenus :
|
|
|
|
```text
|
|
ksp-worker-raw-retriever
|
|
ksp-worker-core-processor
|
|
ksp-worker-generic-materializer
|
|
ksp-worker-domain-projector
|
|
```
|
|
|
|
Le dernier nom reste provisoire.
|
|
|
|
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 :
|
|
|
|
```text
|
|
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 : 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
|
|
|
|
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 :
|
|
|
|
```text
|
|
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.
|