173 lines
7.4 KiB
Markdown
173 lines
7.4 KiB
Markdown
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
|
<!-- version: 7 -->
|
|
|
|
# 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) et Execution/Policy dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.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
|
|
|
|
`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 :
|
|
|
|
```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
|
|
|
|
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.
|