v0.0.3-pre.005
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/IDEAS.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Idées à explorer
|
||||
|
||||
@@ -40,7 +40,7 @@ L'UI sélectionne/injecte une implémentation réutilisable ; elle ne doit pas d
|
||||
|
||||
`ksp-execution-lib` est retenu comme orchestration spécialisée entre programme, policy, wallet et transport. Il dépend de `ksp-program-api`, pas de l'implémentation `ksp-program-lib`.
|
||||
|
||||
Les types exacts d'opération préparée et de policy restent à définir en `0.0.3-pre.004`.
|
||||
La frontière d'orchestration et les checkpoints de policy sont définis dans `007-EXECUTION_AND_POLICY.md`; les types Rust exacts restent à définir avec l'implémentation.
|
||||
|
||||
### Scenarios : norme avant API
|
||||
|
||||
@@ -192,3 +192,20 @@ Définir la politique lorsqu'un registry reçoit plusieurs implémentations capa
|
||||
**Status :** À explorer avec les premiers modules
|
||||
|
||||
Le principe `domain/program/capability` est retenu. Les noms exacts des dossiers courts (`dec`, `exec_prep`) seront validés avec la première vraie arborescence.
|
||||
|
||||
|
||||
## Execution — idées d'implémentation
|
||||
|
||||
### Composition de policies
|
||||
|
||||
**Status :** À explorer
|
||||
|
||||
Évaluer, lorsque plusieurs policies réelles existent, s'il est utile de composer des policies spécialisées (réseau, montants, risque, lifecycle/deprecated, approval utilisateur, etc.) derrière un contrat commun.
|
||||
|
||||
Ne pas imposer cette composition dans `ksp-execution-policy-api` avant qu'un cas concret ne démontre les règles de priorité, union des requirements et traitement des conflits.
|
||||
|
||||
### Reprise après approbation externe
|
||||
|
||||
**Status :** À explorer avec la première UI concernée
|
||||
|
||||
Définir un mécanisme sûr de suspension/reprise d'une exécution lorsque la policy demande une approbation externe, sans faire dépendre la couche execution d'une UI ou de Tauri.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/000-README.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Architecture KSP
|
||||
|
||||
@@ -22,6 +22,7 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
|
||||
3. [`003-COMPONENT_CONTRACTS.md`](003-COMPONENT_CONTRACTS.md) — frontières initiales des composants structurants et contrats déjà acquis ;
|
||||
4. [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) — inventaire courant des domaines, APIs, bibliothèques, workers, jobs, scénarios et applications candidates ;
|
||||
5. [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md) — graphe de dépendances retenu, dépendances interdites et frontières de conversion/composition ;
|
||||
6. [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) — propriété des contrats wire, politique de dépendances codecs/interfaces, API Program ouverte, preparation d'exécution et extensibilité externe.
|
||||
6. [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) — propriété des contrats wire, politique de dépendances codecs/interfaces, API Program ouverte, preparation d'exécution et extensibilité externe ;
|
||||
7. [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md) — policy multi-checkpoints, orchestration transactionnelle, wallet/transport, retry, approval externe et résultat d'exécution.
|
||||
|
||||
`004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Couches et dépendances KSP
|
||||
|
||||
@@ -18,7 +18,11 @@ Positionnement actuellement retenu :
|
||||
- `ksp-core-lib` — primitives et contrats fondamentaux réellement transversaux, type d'erreur commun KSP et responsabilité autrefois séparée des identifiants de programmes ;
|
||||
- `ksp-interface-lib` — façade KSP des interfaces/wire on-chain nécessaires aux autres bibliothèques ;
|
||||
- `ksp-config-lib` — contrats, chargement/résolution et manipulation autorisée de la configuration et des profils ;
|
||||
- `ksp-logging-lib` — fondations communes de logging/tracing.
|
||||
- `ksp-logging-lib` — façade commune de logging/tracing, propriétaire de l'initialisation et des dépendances directes `tracing`, `tracing-appender` et `tracing-subscriber`.
|
||||
|
||||
`ksp-logging-lib` peut dépendre de `ksp-core-lib` pour le contrat commun `Error` / `Result`. La relation inverse n'est pas requise : `ksp-core-lib` reste sans dépendance logging tant qu'aucun besoin réel ne la justifie.
|
||||
|
||||
Les crates KSP contenant du comportement/runtime peuvent dépendre directement de `ksp-logging-lib` afin de produire des logs structurés aux niveaux `error`, `warn`, `info`, `debug` et `trace`. Les crates `*-api` purement déclaratives n'ajoutent pas cette dépendance sans comportement réel à logger.
|
||||
|
||||
Une bibliothèque N1 ne doit pas dépendre d'une fonctionnalité métier située dans une couche supérieure.
|
||||
|
||||
@@ -68,9 +72,9 @@ W1 :
|
||||
|
||||
Les consommateurs des notifications W1 décident eux-mêmes s'ils doivent décoder, matérialiser ou effectuer un autre traitement.
|
||||
|
||||
### W2
|
||||
### Workers de processing futurs
|
||||
|
||||
W2 est réservé à une phase ultérieure de processing. Son contrat précis sera défini après stabilisation du décodage, de la matérialisation et du store. Il ne doit pas être confondu avec W1.
|
||||
Le processing continu n'est plus modélisé comme un unique W2. La direction actuelle sépare `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector` afin de respecter les frontières durables raw -> Core -> matérialisation générique -> projections de domaine. Leur détail sera repris dans la tranche consacrée aux workers/data.
|
||||
|
||||
## N4 — Exécutables
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Contrats initiaux des composants KSP
|
||||
|
||||
@@ -9,7 +9,7 @@ Ce document enregistre les frontières déjà suffisamment claires pour guider l
|
||||
|
||||
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) et les contrats Wire/Program dans [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md).
|
||||
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
|
||||
|
||||
@@ -43,30 +43,48 @@ 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.
|
||||
`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.
|
||||
|
||||
Le contrat public séparé suivant est retenu :
|
||||
Une exécution réelle via `ksp-execution-lib` reçoit explicitement une policy ; aucun fallback permissif implicite n'est prévu.
|
||||
|
||||
```text
|
||||
ksp-execution-policy-api
|
||||
```
|
||||
La policy peut être évaluée à plusieurs checkpoints afin d'intégrer des informations obtenues pendant le cycle, notamment le résultat de simulation.
|
||||
|
||||
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.
|
||||
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 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.
|
||||
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` est retenu comme pipeline/orchestrateur spécialisé pour relier :
|
||||
`ksp-execution-lib` consomme fondamentalement `PreparedProgramExecution` conforme à `ksp-program-api` et ne dépend pas de `ksp-program-lib`.
|
||||
|
||||
- la préparation/sémantique programme ;
|
||||
- une implémentation de `ksp-execution-policy-api` ;
|
||||
- `ksp-wallet-lib` ;
|
||||
- `ksp-onchain-transport-lib`.
|
||||
Il orchestre :
|
||||
|
||||
Le but est d'éviter que `ksp-program-lib` dépende directement du wallet/transport uniquement pour réaliser le cycle réseau/signature.
|
||||
- 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.
|
||||
|
||||
`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`.
|
||||
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
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Inventaire initial des composants KSP
|
||||
|
||||
@@ -21,41 +21,41 @@ Le premier inventaire a été produit en `0.0.3-pre.002`. `pre.003` l'a corrigé
|
||||
|
||||
## Inventaire synthétique
|
||||
|
||||
| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale |
|
||||
|-------------------------|---------------------------------------------|-------------------------|-------------------|-----------------------------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
|
||||
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées |
|
||||
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | logging/tracing commun |
|
||||
| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles |
|
||||
| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics ouverts de décodage, préparation d'exécution, descriptors et registry |
|
||||
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders et `ProgramExecutionPreparer` officiels organisés par domaine/programme/capacité |
|
||||
| Program extension | `ksp-program-<name>-lib` | lib externe/optionnelle | N2 | À la demande | dès besoin | implémentation externe de `ksp-program-api` pour un Program ID non encore intégré officiellement |
|
||||
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | `0.2.x+` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution |
|
||||
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | orchestration spécialisée entre opération préparée, policy, wallet et transport ; dépend de `ksp-program-api`, pas de `ksp-program-lib` |
|
||||
| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store |
|
||||
| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain |
|
||||
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
|
||||
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
|
||||
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
|
||||
| Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées |
|
||||
| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries |
|
||||
| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus |
|
||||
| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur |
|
||||
| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data |
|
||||
| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique |
|
||||
| Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core |
|
||||
| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine |
|
||||
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
|
||||
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
|
||||
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
|
||||
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
|
||||
| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant |
|
||||
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
|
||||
| Specialized pipelines | `ksp-pipeline-<role>-lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale |
|
||||
| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
|
||||
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
|
||||
| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana |
|
||||
| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX |
|
||||
| Domaine | Composant | Nature | Niveau provisoire | Statut | Première série envisagée | Responsabilité principale |
|
||||
|-------------------------|---------------------------------------------|-------------------------|-------------------|-----------------------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Core | `ksp-core-lib` | lib | N1 | Retenu | `0.1.x` | `Error` commun, Program IDs, primitives/contrats réellement transversaux |
|
||||
| Configuration | `ksp-config-lib` | lib | N1 | Retenu | `0.1.x` | documents de configuration, profils, résolution, modifications autorisées |
|
||||
| Logging | `ksp-logging-lib` | lib | N1 | Retenu | `0.1.x` | façade unique `tracing`/appender/subscriber, initialisation et logging structuré KSP ; peut dépendre de core pour Error/Result |
|
||||
| Wire Solana | `ksp-interface-lib` | lib | N1 | Retenu | `0.2.x` | façade wire on-chain, réexports contrôlés et réimplémentations compatibles |
|
||||
| Program API | `ksp-program-api` | API | N2 contrat | Retenu | `0.2.x` | contrats publics ouverts de décodage, préparation d'exécution, descriptors et registry |
|
||||
| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders et `ProgramExecutionPreparer` officiels organisés par domaine/programme/capacité |
|
||||
| Program extension | `ksp-program-<name>-lib` | lib externe/optionnelle | N2 | À la demande | dès besoin | implémentation externe de `ksp-program-api` pour un Program ID non encore intégré officiellement |
|
||||
| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Retenu | premier besoin d'exécution réelle | policy obligatoire, multi-checkpoints, décision/requirements sans wallet/réseau/UI |
|
||||
| Execution orchestration | `ksp-execution-lib` | lib | N3 | Retenu | premier besoin d'exécution réelle | consomme `PreparedProgramExecution`; orchestre policy/simulation/signature/submission/confirmation/retry sans dépendre de `ksp-program-lib` ou du store |
|
||||
| Transport on-chain | `ksp-onchain-transport-lib` | lib | N2 | Retenu | `0.2.x` | RPC/WS/providers et modèles de transport homogènes, sans dépendance store |
|
||||
| Transport off-chain | `ksp-offchain-transport-lib` | lib | N2 | Retenu, implémentation différable | premier besoin réel | accès metadata, prix, quotes, routage et autres ressources hors blockchain |
|
||||
| Wallet | `ksp-wallet-lib` | lib | N2 | Retenu | `0.2.x` | format wallet KSP, lecture/protection/import/export, pubkey, secret/signature |
|
||||
| Materializer API | `ksp-materializer-api` | API | N3 contrat | Retenu | `0.3.x` | contrats publics/extensibles de matérialisation |
|
||||
| Materializer impl. | `ksp-materializer-lib` | lib | N3 | Retenu | `0.3.x+` | materializers officiels KSP |
|
||||
| Store API | `ksp-store-api` | API | N3 contrat | Retenu | `0.3.x` | contrats backend-agnostic, modèles persistants et notifications de données persistées |
|
||||
| Store impl. | `ksp-store-lib` | lib | N3 | Retenu | `0.3.x` | PostgreSQL de référence, migrations, repositories, queries |
|
||||
| Worker lifecycle | `ksp-worker-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle commun des services continus |
|
||||
| Worker control | `ksp-worker-control-lib` | lib | N3 | Retenu | `0.3.x+` | gouvernance réutilisable des workers pour managers/apps/orchestrateur |
|
||||
| Live raw acquisition | `ksp-worker-raw-retriever` | worker | N4 | Retenu | `0.3.x` | acquisition live/quasi-live -> raw persisté -> notification data |
|
||||
| Raw -> Core | `ksp-worker-core-processor` | worker | N4 | Futur retenu | `0.6.x` | transformer le raw persisté en Core canonique |
|
||||
| Core -> generic mat. | `ksp-worker-generic-materializer` | worker | N4 | Futur retenu | `0.6.x` | produire la matérialisation/journal générique depuis le Core |
|
||||
| Domain projection | `ksp-worker-domain-projector` | worker | N4 | Futur retenu, nom provisoire | `0.6.x` | matérialiser/classer/stocker les projections spécialisées par domaine |
|
||||
| Job lifecycle | `ksp-job-api` | API | N3 contrat | Retenu | `0.3.x` | lifecycle/progression commun des travaux déclenchés et terminables |
|
||||
| Historical backfill | `ksp-job-backfill` | job | N4 | Retenu | `0.3.x` | acquisition historique avec pagination, progression, checkpoint/reprise |
|
||||
| Other jobs | `ksp-job-<role>` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques |
|
||||
| Scenarios | `ksp-scenario-<domain>-lib` | lib | N3 | Retenu | `0.4.x+` | scénarios de validation spécialisés par domaine |
|
||||
| Scenario common API | `ksp-scenario-api` | API | — | Non retenu actuellement | — | préférer une norme de scénario souple plutôt qu'un trait commun contraignant |
|
||||
| Scenario demo apps | `ksp-app-scenario-<domain>-<env>-desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante |
|
||||
| Specialized pipelines | `ksp-pipeline-<role>-lib` ou autre forme | variable | N3/N4 | À la demande | selon besoin | pipeline concret et borné ; aucune crate pipeline globale |
|
||||
| Trading Intelligence | noms à définir | API/libs/jobs | N3+ | Futur retenu | `0.7.x` | statistiques, features, signaux, anomalies, backtests, ML |
|
||||
| Trading operation/app | noms à définir | libs/apps | N3/N4 | Futur retenu | après Trading Intelligence | politique/automatisation de trading et application monoposte |
|
||||
| Solana explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration générale Solana |
|
||||
| DEX explorer | noms à définir | libs/apps | N3/N4 | Futur retenu | futur | exploration/analyse DEX |
|
||||
|
||||
## APIs séparées retenues
|
||||
|
||||
@@ -78,36 +78,32 @@ Aucune API commune worker+job n'est prévue.
|
||||
|
||||
## Execution policy et orchestration
|
||||
|
||||
### Direction retenue après `pre.003`
|
||||
La frontière détaillée est définie dans [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md).
|
||||
|
||||
La direction privilégiée est une orchestration supérieure plutôt qu'une dépendance directe de `ksp-program-lib` vers le wallet et le transport :
|
||||
Principes retenus :
|
||||
|
||||
```text
|
||||
policy implementation
|
||||
^
|
||||
|
|
||||
ksp-execution-policy-api
|
||||
^
|
||||
|
|
||||
ksp-execution-lib
|
||||
/ | \
|
||||
/ | \
|
||||
program side wallet onchain transport
|
||||
PreparedProgramExecution
|
||||
|
|
||||
v
|
||||
ksp-execution-lib
|
||||
| | |
|
||||
policy wallet onchain transport
|
||||
```
|
||||
|
||||
`ksp-program-lib` doit rester propriétaire de la sémantique technique des programmes et de la préparation des opérations, sans posséder la politique de sécurité d'un produit ni le cycle réseau complet.
|
||||
- `ksp-execution-lib` dépend de `ksp-program-api`, pas de `ksp-program-lib` ;
|
||||
- une policy est explicitement fournie pour toute exécution réelle ;
|
||||
- la policy peut être évaluée à plusieurs checkpoints ;
|
||||
- une policy décide/contraint mais n'exécute pas de réseau/signature/UI ;
|
||||
- Program constraints, options caller et policy constraints restent trois sources distinctes ;
|
||||
- wallet/signers et transport/provider sont fournis par la composition supérieure ;
|
||||
- simulation/submission/status sont des primitives transport orchestrées par execution ;
|
||||
- signature est une capacité wallet orchestrée par execution ;
|
||||
- retry réseau identique et retry de lifecycle d'exécution restent distincts ;
|
||||
- une approbation externe peut suspendre/reprendre l'exécution sans faire dépendre la policy de l'UI ;
|
||||
- aucun accès Store depuis `ksp-execution-lib`.
|
||||
|
||||
`ksp-execution-policy-api` permettrait plusieurs politiques incompatibles mais conformes au même contrat, par exemple :
|
||||
|
||||
- politique permissive et bornée d'un scénario Devnet ;
|
||||
- politique plus stricte d'une future application générale ;
|
||||
- politique spécialisée d'un futur produit de trading.
|
||||
|
||||
Une application UI ne doit pas enfouir cette logique dans ses commandes ou composants. Elle sélectionne/injecte une implémentation réutilisable située dans la crate de scénario ou de domaine appropriée.
|
||||
|
||||
Aucune `ksp-execution-policy-lib` générique n'est retenue actuellement. Des implémentations réutilisables pourront être créées plus tard si plusieurs consommateurs partagent réellement la même politique.
|
||||
|
||||
`ksp-execution-lib` dépend de `ksp-program-api` et non de `ksp-program-lib`. La forme exacte des plans/opérations préparées et le mécanisme d'injection/appel sont reportés à `pre.004`.
|
||||
`ksp-logging-lib` est consommé transversalement par les crates runtime qui doivent logger, sans imposer une dépendance aux crates `*-api` déclaratives ni à `ksp-core-lib`.
|
||||
|
||||
## Transport on-chain
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Graphe de dépendances KSP
|
||||
|
||||
@@ -74,16 +74,37 @@ Un orchestrateur futur peut consommer les deux familles séparément sans les fu
|
||||
```text
|
||||
ksp-core-lib
|
||||
|
||||
ksp-config-lib -> ksp-core-lib
|
||||
ksp-logging-lib -> ksp-core-lib
|
||||
ksp-config-lib -> ksp-core-lib
|
||||
ksp-config-lib -> ksp-logging-lib # lorsque du runtime logging est nécessaire
|
||||
ksp-interface-lib -> ksp-core-lib
|
||||
ksp-interface-lib -> ksp-logging-lib # lorsque du runtime logging est nécessaire
|
||||
```
|
||||
|
||||
`ksp-core-lib` ne dépend d'aucun composant KSP supérieur.
|
||||
|
||||
`ksp-interface-lib` est propriétaire de la façade wire et peut dépendre des crates externes Solana/interface explicitement autorisées par `RULES_DEPENDENCIES.md`.
|
||||
|
||||
`ksp-config-lib` et `ksp-logging-lib` sont transversaux. Les composants supérieurs peuvent les consommer lorsqu'un besoin réel existe ; cette possibilité ne doit pas être transformée en dépendance obligatoire universelle.
|
||||
`ksp-logging-lib` est la façade logging/tracing KSP et peut dépendre de `ksp-core-lib` pour `Error` / `Result`. `ksp-core-lib` n'a pas de dépendance inverse vers le logging. Les composants comportant du runtime peuvent dépendre directement de `ksp-logging-lib`; cette permission n'oblige pas les crates purement déclaratives à le faire.
|
||||
|
||||
---
|
||||
|
||||
# Graphe Logging
|
||||
|
||||
```text
|
||||
ksp-logging-lib
|
||||
-> ksp-core-lib
|
||||
-> tracing / tracing-appender / tracing-subscriber
|
||||
|
||||
runtime crate
|
||||
-> ksp-logging-lib
|
||||
```
|
||||
|
||||
`ksp-logging-lib` est la seule façade KSP propriétaire de l'initialisation/configuration tracing. Une crate runtime ne dépend normalement pas directement de `tracing`.
|
||||
|
||||
Exception technique possible : une application/framework, notamment Tauri, peut devoir intégrer un plugin tracing. Cette adaptation ne crée pas une seconde politique de logging parallèle.
|
||||
|
||||
`ksp-core-lib` et les crates `*-api` purement déclaratives n'ont pas de dépendance logging obligatoire.
|
||||
|
||||
---
|
||||
|
||||
@@ -170,8 +191,6 @@ Le runtime peut composer registry officiel + registry/implémentations externes
|
||||
|
||||
# Graphe Execution / Policy
|
||||
|
||||
`ksp-execution-policy-api` et `ksp-execution-lib` sont retenus comme composants.
|
||||
|
||||
```text
|
||||
ksp-execution-policy-api
|
||||
-> ksp-program-api
|
||||
@@ -182,48 +201,56 @@ ksp-execution-lib
|
||||
-> ksp-execution-policy-api
|
||||
-> ksp-wallet-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-logging-lib
|
||||
-> ksp-core-lib
|
||||
```
|
||||
|
||||
## Décision importante
|
||||
`ksp-execution-lib` ne dépend pas de `ksp-program-lib` et reçoit fondamentalement une opération déjà préparée conforme à `ksp-program-api`.
|
||||
|
||||
`ksp-execution-lib` **ne dépend pas de `ksp-program-lib`**.
|
||||
## Policy obligatoire et multi-checkpoints
|
||||
|
||||
Il consomme le contrat public de `ksp-program-api` et reçoit :
|
||||
Toute exécution réelle reçoit explicitement une implémentation de `ksp-execution-policy-api`.
|
||||
|
||||
- soit une opération préparée conforme à ce contrat ;
|
||||
- soit une implémentation injectée du contrat public lorsque l'API finale le justifie.
|
||||
La policy peut être consultée à plusieurs checkpoints (préflight, après simulation, avant submission ou autres points réellement justifiés). Le contrat exact ne doit pas imposer plus de callbacks que nécessaire.
|
||||
|
||||
La forme exacte sera décidée en `pre.004`.
|
||||
La policy peut autoriser/refuser/ajouter des requirements, mais n'appelle ni wallet, ni transport, ni UI.
|
||||
|
||||
Cette règle permet :
|
||||
## Composition supérieure
|
||||
|
||||
Le caller fournit notamment :
|
||||
|
||||
- réseau/provider/transport sélectionné ;
|
||||
- wallet/signers sélectionnés ;
|
||||
- options d'exécution.
|
||||
|
||||
`ksp-execution-lib` vérifie/compose ces éléments avec les contraintes techniques de `PreparedProgramExecution` et les contraintes supplémentaires de policy.
|
||||
|
||||
## Simulation / signature / submission / confirmation
|
||||
|
||||
- primitive simulation/submission/status -> `ksp-onchain-transport-lib` ;
|
||||
- orchestration de ces étapes -> `ksp-execution-lib` ;
|
||||
- primitive signature -> `ksp-wallet-lib` ;
|
||||
- résolution/coordination des signers -> `ksp-execution-lib`.
|
||||
|
||||
## Retry
|
||||
|
||||
Retry technique d'un appel réseau identique -> transport.
|
||||
|
||||
Retry qui change le lifecycle (nouveau blockhash, reconstruction, resimulation, resignature, resubmission) -> execution, éventuellement limité par policy.
|
||||
|
||||
## Approbation externe
|
||||
|
||||
Une policy peut produire un requirement d'approbation externe. `ksp-execution-lib` peut retourner un état suspendu/reprenable ; l'UI obtient l'approbation sans être appelée directement par la policy ou l'execution lib.
|
||||
|
||||
## Store
|
||||
|
||||
```text
|
||||
ksp-program-lib ------------------\
|
||||
external-program-implementation ---+--> ksp-program-api --> execution
|
||||
other-compatible-implementation ---/
|
||||
ksp-execution-policy-api -X-> ksp-store-api
|
||||
ksp-execution-lib -X-> ksp-store-api
|
||||
ksp-execution-lib -X-> ksp-store-lib
|
||||
```
|
||||
|
||||
sans rendre l'orchestration dépendante de l'implémentation officielle.
|
||||
|
||||
## Policy
|
||||
|
||||
`ksp-execution-policy-api` définit le contrat d'évaluation, pas la policy d'un produit.
|
||||
|
||||
Une implémentation peut appartenir à :
|
||||
|
||||
- `ksp-scenario-<domain>-lib` pour une demo/scenario Devnet ;
|
||||
- une future bibliothèque de domaine pour une application générale ;
|
||||
- une future bibliothèque trading spécialisée.
|
||||
|
||||
Aucune `ksp-execution-policy-lib` générique n'est prévue tant qu'une policy commune réelle n'existe pas.
|
||||
|
||||
Une policy :
|
||||
|
||||
- autorise/refuse/contraint une exécution ;
|
||||
- ne signe pas ;
|
||||
- ne choisit pas le backend réseau ;
|
||||
- n'envoie pas elle-même une transaction.
|
||||
La persistence d'un `ExecutionOutcome` est une composition supérieure.
|
||||
|
||||
---
|
||||
|
||||
|
||||
323
docs/architecture/007-EXECUTION_AND_POLICY.md
Normal file
323
docs/architecture/007-EXECUTION_AND_POLICY.md
Normal file
@@ -0,0 +1,323 @@
|
||||
<!-- file: docs/architecture/007-EXECUTION_AND_POLICY.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Execution et Policy
|
||||
|
||||
## Objet
|
||||
|
||||
Ce document constitue la sortie principale de `0.0.3-pre.005`.
|
||||
|
||||
Il précise la frontière entre :
|
||||
|
||||
- `ProgramExecutionPreparer` et `PreparedProgramExecution` ;
|
||||
- `ksp-execution-policy-api` ;
|
||||
- `ksp-execution-lib` ;
|
||||
- `ksp-wallet-lib` ;
|
||||
- `ksp-onchain-transport-lib` ;
|
||||
- l'interface/application qui fournit le contexte et les approbations externes.
|
||||
|
||||
Les types Rust exacts restent volontairement à définir avec la première implémentation réelle.
|
||||
|
||||
## Chaîne générale
|
||||
|
||||
```text
|
||||
ProgramExecutionRequest
|
||||
|
|
||||
v
|
||||
ProgramExecutionPreparer
|
||||
|
|
||||
v
|
||||
PreparedProgramExecution
|
||||
|
|
||||
v
|
||||
ksp-execution-lib
|
||||
|
|
||||
+--> policy checkpoints
|
||||
+--> transaction/message assembly
|
||||
+--> simulation si requise
|
||||
+--> signature
|
||||
+--> submission
|
||||
+--> confirmation
|
||||
|
|
||||
v
|
||||
ExecutionOutcome / pending requirement / error
|
||||
```
|
||||
|
||||
`ksp-program-lib` prépare la sémantique protocolaire. `ksp-execution-lib` orchestre le cycle transactionnel. Ces responsabilités ne sont pas fusionnées.
|
||||
|
||||
## Entrée fondamentale de `ksp-execution-lib`
|
||||
|
||||
L'entrée fondamentale de `ksp-execution-lib` est une opération déjà préparée conformément à `ksp-program-api`, conceptuellement `PreparedProgramExecution`.
|
||||
|
||||
`ksp-execution-lib` ne dépend pas de `ksp-program-lib` et ne reçoit pas des requêtes spécifiques à Token, Meteora, Raydium ou autre protocole.
|
||||
|
||||
Un helper de composition `prepare + execute` pourra être ajouté plus tard s'il apporte une valeur réelle, mais il ne remplace pas la frontière fondamentale.
|
||||
|
||||
## `ksp-execution-policy-api`
|
||||
|
||||
`ksp-execution-policy-api` est un contrat public de décision. Il ne fournit pas une policy générique KSP.
|
||||
|
||||
Une implémentation de policy appartient au contexte qui en a besoin, par exemple :
|
||||
|
||||
- une crate `ksp-scenario-<domain>-lib` pour une demo Devnet ;
|
||||
- une future bibliothèque d'application générale ;
|
||||
- une future bibliothèque spécialisée Trading Intelligence / trading opérationnel.
|
||||
|
||||
Aucune `ksp-execution-policy-lib` commune n'est créée sans policy réellement commune.
|
||||
|
||||
## Policy obligatoire pour une exécution réelle
|
||||
|
||||
Une exécution réelle via `ksp-execution-lib` doit recevoir explicitement une implémentation de `ksp-execution-policy-api`.
|
||||
|
||||
Il n'existe pas de fallback implicite « allow all » pour la production.
|
||||
|
||||
Les tests peuvent utiliser une policy explicitement permissive lorsqu'ils ont besoin de tester le cycle d'exécution indépendamment de règles produit.
|
||||
|
||||
## Policy multi-checkpoints
|
||||
|
||||
Une policy n'est pas nécessairement évaluée une seule fois au début.
|
||||
|
||||
Certaines décisions ont besoin d'informations qui n'existent qu'après une étape technique, en particulier la simulation.
|
||||
|
||||
Direction conceptuelle :
|
||||
|
||||
```text
|
||||
Prepared
|
||||
|
|
||||
v
|
||||
preflight policy
|
||||
|
|
||||
v
|
||||
simulation éventuelle
|
||||
|
|
||||
v
|
||||
post-simulation policy
|
||||
|
|
||||
v
|
||||
signature
|
||||
|
|
||||
v
|
||||
pre-submission policy
|
||||
|
|
||||
v
|
||||
submission / confirmation
|
||||
```
|
||||
|
||||
Les noms et le nombre exact de checkpoints seront définis avec l'API réelle. Le contrat doit rester extensible sans imposer des callbacks inutiles à toutes les policies.
|
||||
|
||||
## Une policy décide, elle n'exécute pas
|
||||
|
||||
Une policy peut conceptuellement :
|
||||
|
||||
- autoriser ;
|
||||
- refuser ;
|
||||
- ajouter/resserrer des exigences ;
|
||||
- exiger une simulation ;
|
||||
- exiger une approbation externe ;
|
||||
- imposer un niveau minimum de confirmation ;
|
||||
- imposer des limites de retry/exécution.
|
||||
|
||||
Une policy ne :
|
||||
|
||||
- signe pas ;
|
||||
- sélectionne pas un secret wallet ;
|
||||
- appelle pas RPC ;
|
||||
- n'envoie pas une transaction ;
|
||||
- n'ouvre pas une fenêtre Tauri ;
|
||||
- ne bloque pas en attente d'une interaction UI.
|
||||
|
||||
## Trois sources de contraintes
|
||||
|
||||
L'orchestration distingue trois origines de contraintes.
|
||||
|
||||
### Contraintes Program
|
||||
|
||||
Produites par `ProgramExecutionPreparer` dans `PreparedProgramExecution` :
|
||||
|
||||
- comptes requis ;
|
||||
- signers/authorities requis ;
|
||||
- ordre et contenu des instructions ;
|
||||
- PDA ;
|
||||
- invariants/contraintes protocolaires.
|
||||
|
||||
Elles sont techniques et non négociables par une policy.
|
||||
|
||||
### Options/contexte du consommateur
|
||||
|
||||
Le niveau supérieur fournit le contexte d'exécution :
|
||||
|
||||
- réseau/profil choisi ;
|
||||
- wallet/signers sélectionnés ;
|
||||
- commitment/timeout souhaités ;
|
||||
- options de simulation ;
|
||||
- autres choix exposés par l'application/scénario.
|
||||
|
||||
### Contraintes Policy
|
||||
|
||||
La policy peut refuser ou resserrer les options du consommateur, mais ne peut pas violer les contraintes techniques Program.
|
||||
|
||||
## Wallet
|
||||
|
||||
`ksp-execution-lib` utilise `ksp-wallet-lib` pour les capacités de signature mais ne choisit pas arbitrairement un wallet.
|
||||
|
||||
Le contexte supérieur fournit les signers/wallet handles sélectionnés ; l'orchestration vérifie qu'ils satisfont les authorities/signers requis par `PreparedProgramExecution`.
|
||||
|
||||
Les secrets ne sont jamais transportés dans `PreparedProgramExecution`.
|
||||
|
||||
## Transport on-chain
|
||||
|
||||
`ksp-execution-lib` utilise `ksp-onchain-transport-lib` pour les primitives réseau nécessaires, notamment selon le besoin :
|
||||
|
||||
- récupération des données réseau nécessaires à la construction finale ;
|
||||
- simulation ;
|
||||
- submission ;
|
||||
- status/confirmation.
|
||||
|
||||
`ksp-execution-lib` ne choisit pas arbitrairement Helius, RPC public, WS ou autre provider. Le contexte/configuration supérieur fournit la cible/transport approprié.
|
||||
|
||||
Le choix du provider est distinct de la policy d'exécution.
|
||||
|
||||
## Simulation
|
||||
|
||||
La primitive réseau de simulation appartient à `ksp-onchain-transport-lib`.
|
||||
|
||||
L'orchestration de la simulation appartient à `ksp-execution-lib` : elle décide quand appeler la primitive selon `PreparedProgramExecution`, options et exigences de policy.
|
||||
|
||||
La policy peut rendre la simulation obligatoire et peut évaluer son résultat, mais n'effectue pas elle-même l'appel réseau.
|
||||
|
||||
## Signature
|
||||
|
||||
`ksp-execution-lib` assemble le message/transaction selon les contrats techniques retenus, résout les signers requis depuis le contexte puis appelle `ksp-wallet-lib` pour les signatures.
|
||||
|
||||
Les crates Solana précises nécessaires aux messages/transactions seront évaluées au moment de l'implémentation selon la même politique de dépendances modernes que les autres interfaces KSP.
|
||||
|
||||
## Submission et confirmation
|
||||
|
||||
Les primitives réseau de submission/status appartiennent à `ksp-onchain-transport-lib`.
|
||||
|
||||
Le lifecycle :
|
||||
|
||||
```text
|
||||
submitted
|
||||
-> processed / confirmed / finalized
|
||||
-> timeout / failure
|
||||
```
|
||||
|
||||
est orchestré par `ksp-execution-lib`.
|
||||
|
||||
Une policy peut imposer un minimum de confirmation mais n'implémente pas la boucle de confirmation.
|
||||
|
||||
## Retry transport vs retry d'exécution
|
||||
|
||||
Deux catégories sont distinguées.
|
||||
|
||||
### Retry transport
|
||||
|
||||
Retry technique d'un appel réseau identique, par exemple erreur transitoire de connexion/rate-limit. Il appartient au transport selon ses règles propres.
|
||||
|
||||
### Retry d'exécution
|
||||
|
||||
Un retry qui modifie le lifecycle de l'opération, par exemple :
|
||||
|
||||
- blockhash expiré ;
|
||||
- reconstruction ;
|
||||
- nouvelle simulation ;
|
||||
- nouvelle signature ;
|
||||
- nouvelle submission.
|
||||
|
||||
Il appartient à `ksp-execution-lib` et peut être limité/refusé par la policy.
|
||||
|
||||
## Approbation externe et suspension
|
||||
|
||||
Une policy peut demander une approbation externe sans connaître l'UI.
|
||||
|
||||
`ksp-execution-lib` doit pouvoir exposer un état/requirement suspendu conceptuel permettant au caller :
|
||||
|
||||
1. de recevoir la demande ;
|
||||
2. d'obtenir l'approbation via son interface propre ;
|
||||
3. de reprendre l'exécution de manière contrôlée.
|
||||
|
||||
Le mécanisme exact de token/resume sera défini avec le premier besoin réel.
|
||||
|
||||
Une application Tauri affiche éventuellement le dialogue ; ni la policy ni `ksp-execution-lib` ne dépendent de Tauri pour cela.
|
||||
|
||||
## Résultat d'exécution
|
||||
|
||||
Le résultat doit pouvoir exposer conceptuellement :
|
||||
|
||||
- identité de l'opération préparée ;
|
||||
- identité/signature transactionnelle lorsqu'elle existe ;
|
||||
- résultat de simulation lorsqu'elle a eu lieu ;
|
||||
- résultat de submission ;
|
||||
- état de confirmation ;
|
||||
- warnings ;
|
||||
- informations de décisions/requirements utiles au caller ;
|
||||
- erreur/état final ou suspendu.
|
||||
|
||||
`ksp-execution-lib` ne persiste pas automatiquement ce résultat et ne dépend pas du store.
|
||||
|
||||
La persistence éventuelle appartient à un composant supérieur de composition.
|
||||
|
||||
## Logging transversal
|
||||
|
||||
`ksp-logging-lib` est la façade commune de logging/tracing KSP.
|
||||
|
||||
Elle possède directement les dépendances techniques de logging, notamment :
|
||||
|
||||
```text
|
||||
tracing
|
||||
tracing-appender
|
||||
tracing-subscriber
|
||||
```
|
||||
|
||||
et peut dépendre de `ksp-core-lib` pour `Error` / `Result`.
|
||||
|
||||
Elle possède l'initialisation/configuration du système de logging et expose une façade KSP paramétrable (target/domain/champs structurés et niveaux selon l'API finale).
|
||||
|
||||
Les crates runtime KSP ne dépendent normalement pas directement de `tracing`; elles utilisent `ksp-logging-lib` pour produire des événements :
|
||||
|
||||
```text
|
||||
error
|
||||
warn
|
||||
info
|
||||
debug
|
||||
trace
|
||||
```
|
||||
|
||||
L'API exacte peut utiliser fonctions, macros ou une combinaison des deux afin de préserver les propriétés utiles de `tracing`; ce détail est reporté à l'implémentation de `ksp-logging-lib`.
|
||||
|
||||
Les applications Tauri constituent une exception technique possible lorsqu'un plugin tel que `tauri-plugin-tracing` impose une intégration directe au framework. Cette adaptation ne doit pas créer une seconde politique de logging parallèle : `ksp-logging-lib` reste la façade/propriétaire KSP.
|
||||
|
||||
`ksp-core-lib` n'a pas besoin de dépendre de `ksp-logging-lib` dans l'architecture actuelle.
|
||||
|
||||
Les crates `*-api` purement déclaratives ne dépendent pas du logging par défaut.
|
||||
|
||||
## Composition de policies
|
||||
|
||||
La composition de plusieurs policies spécialisées (réseau, montants, risque, deprecated operation, approval utilisateur, etc.) reste une idée à évaluer.
|
||||
|
||||
Elle n'est pas imposée par `ksp-execution-policy-api` tant que les premières policies réelles n'ont pas démontré un contrat de composition utile.
|
||||
|
||||
## Dépendances interdites
|
||||
|
||||
```text
|
||||
ksp-execution-policy-api -X-> ksp-wallet-lib
|
||||
ksp-execution-policy-api -X-> ksp-onchain-transport-lib
|
||||
ksp-execution-policy-api -X-> ksp-store-api
|
||||
ksp-execution-policy-api -X-> UI/Tauri
|
||||
|
||||
ksp-execution-lib -X-> ksp-program-lib
|
||||
ksp-execution-lib -X-> ksp-store-api
|
||||
ksp-execution-lib -X-> ksp-store-lib
|
||||
```
|
||||
|
||||
## Questions laissées à l'implémentation
|
||||
|
||||
- types Rust exacts des checkpoints et décisions de policy ;
|
||||
- représentation précise de `ExecutionContext` ;
|
||||
- mécanisme d'approbation suspendue/reprise ;
|
||||
- forme exacte de `ExecutionOutcome` ;
|
||||
- limites/retry defaults ;
|
||||
- crates Solana actuelles pour message/transaction/versioned transaction ;
|
||||
- API fonctions/macros exacte de `ksp-logging-lib` ;
|
||||
- éventuelle composition de policies.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Plan KSP 0.0.3
|
||||
|
||||
@@ -13,7 +13,7 @@ Transformer le brainstorming KSP en architecture, règles, inventaire et plan su
|
||||
- `pre.002` — inventaire initial des composants ;
|
||||
- `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition.
|
||||
|
||||
La tranche `pre.004` est consacrée à Wire/Program. Execution/Policy est volontairement déplacé vers `pre.005` afin de garder des prereleases de planification bornées.
|
||||
Les tranches `pre.004` (Wire/Program) et `pre.005` (Execution/Policy) sont maintenant cadrées/livrées séparément afin de conserver des prereleases de planification bornées.
|
||||
|
||||
## Décisions structurantes actuelles
|
||||
|
||||
@@ -68,13 +68,19 @@ Livré :
|
||||
|
||||
### `pre.005` — Execution et Policy
|
||||
|
||||
- détailler `ksp-execution-policy-api` ;
|
||||
- détailler `ksp-execution-lib` ;
|
||||
- consommer `PreparedProgramExecution` sans dépendre de `ksp-program-lib` ;
|
||||
- définir les étapes policy, simulation, wallet/signature, transport/envoi, confirmation ;
|
||||
- déterminer les policies de scenario Devnet vs produit général ;
|
||||
- traiter erreurs/retry/confirmation et limites de responsabilité ;
|
||||
- scinder à nouveau si la tranche devient trop dense.
|
||||
Livré :
|
||||
|
||||
- `ksp-execution-policy-api` comme contrat de décision obligatoire pour une exécution réelle ;
|
||||
- policy multi-checkpoints ;
|
||||
- séparation stricte entre décision policy et actions wallet/réseau/UI ;
|
||||
- `ksp-execution-lib` consommant `PreparedProgramExecution` sans dépendre de `ksp-program-lib` ;
|
||||
- distinction Program constraints / caller options / policy constraints ;
|
||||
- wallet/signers et provider sélectionnés par la composition supérieure ;
|
||||
- simulation, signature, submission et confirmation orchestrées avec les primitives des libs propriétaires ;
|
||||
- distinction retry transport / retry lifecycle d'exécution ;
|
||||
- approbation externe suspendue/reprenable ;
|
||||
- résultat d'exécution indépendant du Store ;
|
||||
- `ksp-logging-lib` confirmé comme façade unique tracing du runtime KSP, avec dépendance possible vers Core pour `Error`/`Result`.
|
||||
|
||||
### `pre.006` — Données, store et acquisitions
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_DEPENDENCIES.md -->
|
||||
<!-- version: 3 -->
|
||||
<!-- version: 4 -->
|
||||
|
||||
# Règles des dépendances KSP
|
||||
|
||||
@@ -33,15 +33,29 @@ Elles complètent les règles Rust générales et le graphe de `docs/architectur
|
||||
- **DEP-WIRE-006** — KSP cherche des versions récentes compatibles et ne fixe pas arbitrairement une ancienne version uniquement pour conserver une crate protocolaire remplaçable.
|
||||
- **DEP-WIRE-007** — Une extension Program externe peut posséder temporairement son propre wire lorsqu'aucune interface officielle KSP correspondante n'existe encore.
|
||||
|
||||
## Logging
|
||||
|
||||
- **DEP-LOG-001** — `ksp-logging-lib` est le propriétaire KSP direct de `tracing`, `tracing-appender`, `tracing-subscriber` et de l'initialisation/configuration logging.
|
||||
- **DEP-LOG-002** — `ksp-logging-lib` peut dépendre de `ksp-core-lib` pour le contrat commun `Error` / `Result`.
|
||||
- **DEP-LOG-003** — `ksp-core-lib` ne dépend pas de `ksp-logging-lib` dans l'architecture actuelle.
|
||||
- **DEP-LOG-004** — Les crates KSP comportant du runtime peuvent dépendre directement de `ksp-logging-lib` et ne dépendent normalement pas directement de `tracing`.
|
||||
- **DEP-LOG-005** — Les crates `*-api` purement déclaratives n'ajoutent pas une dépendance logging sans comportement réel à instrumenter.
|
||||
- **DEP-LOG-006** — Une application/framework peut exceptionnellement intégrer directement un plugin/dépendance tracing imposé par son framework, notamment Tauri, sans créer une seconde politique de logging parallèle à `ksp-logging-lib`.
|
||||
|
||||
## Program / Execution
|
||||
|
||||
- **DEP-PROGRAM-001** — `ksp-program-api` peut dépendre de `ksp-core-lib` et `ksp-interface-lib`.
|
||||
- **DEP-PROGRAM-002** — `ksp-program-lib` dépend de `ksp-program-api` et peut dépendre de `ksp-interface-lib`/`ksp-core-lib`.
|
||||
- **DEP-PROGRAM-003** — `ksp-program-api` et `ksp-program-lib` ne dépendent pas du wallet, du transport, du store ou des materializers.
|
||||
- **DEP-PROGRAM-004** — Une implémentation externe `ksp-program-<name>-lib` peut dépendre directement de `ksp-program-api` sans dépendre de `ksp-program-lib`.
|
||||
- **DEP-EXECUTION-001** — `ksp-execution-policy-api` dépend du contrat public Program, pas de l'implémentation `ksp-program-lib`.
|
||||
- **DEP-EXECUTION-002** — `ksp-execution-lib` dépend de `ksp-program-api`, `ksp-execution-policy-api`, `ksp-wallet-lib` et `ksp-onchain-transport-lib`; il ne dépend pas de `ksp-program-lib`.
|
||||
- **DEP-EXECUTION-001** — `ksp-execution-policy-api` dépend du contrat public Program et de Core, pas de `ksp-program-lib`, wallet, transport, store ou UI.
|
||||
- **DEP-EXECUTION-002** — `ksp-execution-lib` dépend de `ksp-program-api`, `ksp-execution-policy-api`, `ksp-wallet-lib`, `ksp-onchain-transport-lib`, `ksp-logging-lib` et Core ; il ne dépend pas de `ksp-program-lib`.
|
||||
- **DEP-EXECUTION-003** — Une implémentation de policy reste située dans une crate de scénario/domaine/produit appropriée et ne devient pas une responsabilité de `ksp-program-lib`.
|
||||
- **DEP-EXECUTION-004** — Une exécution réelle reçoit explicitement une policy ; aucun fallback permissif implicite n'est prévu.
|
||||
- **DEP-EXECUTION-005** — La policy décide/refuse/contraint mais ne réalise pas la simulation, la signature, le transport réseau ou l'interaction UI.
|
||||
- **DEP-EXECUTION-006** — Wallet/signers et provider/transport sont fournis/sélectionnés par la composition supérieure ; `ksp-execution-lib` les orchestre sans définir leur policy de sélection.
|
||||
- **DEP-EXECUTION-007** — Le retry réseau d'un appel identique appartient au transport ; un retry modifiant le lifecycle d'exécution appartient à `ksp-execution-lib`.
|
||||
- **DEP-EXECUTION-008** — `ksp-execution-lib` ne dépend ni de `ksp-store-api` ni de `ksp-store-lib`; la persistence d'un résultat appartient à une composition supérieure.
|
||||
|
||||
## Materializer / Store
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_KSP.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 9 -->
|
||||
|
||||
# Règles spécifiques à KSP
|
||||
|
||||
@@ -33,9 +33,14 @@
|
||||
- **KSP-PROGRAM-004** — 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.
|
||||
- **KSP-PROGRAM-005** — Une opération devenue obsolète mais toujours identifiable/exécutable peut rester implémentée dans l'executor et être marquée `deprecated`.
|
||||
- **KSP-PROGRAM-006** — `ksp-program-lib` ne contient pas la politique de sécurité de production.
|
||||
- **KSP-EXEC-001** — `ksp-execution-policy-api` est retenu comme API publique de policy d'exécution afin que plusieurs contextes puissent fournir des politiques différentes sans modifier `ksp-program-lib`.
|
||||
- **KSP-EXEC-002** — Une application UI sélectionne/injecte une implémentation de policy réutilisable ; elle ne doit pas enfouir une politique d'exécution complexe dans sa couche d'interface.
|
||||
- **KSP-EXEC-003** — `ksp-execution-lib` est retenu comme orchestration spécialisée entre programme, policy, wallet et transport. Il dépend de `ksp-program-api` et non de `ksp-program-lib`.
|
||||
- **KSP-EXEC-001** — `ksp-execution-policy-api` est l'API publique de décision/safety d'exécution ; chaque contexte fournit sa propre implémentation.
|
||||
- **KSP-EXEC-002** — Toute exécution réelle via `ksp-execution-lib` reçoit explicitement une policy ; aucun fallback implicite permissif n'est prévu.
|
||||
- **KSP-EXEC-003** — Une policy peut être évaluée à plusieurs checkpoints et peut autoriser, refuser ou imposer des requirements ; elle ne signe pas, n'appelle pas le réseau et n'interagit pas directement avec l'UI.
|
||||
- **KSP-EXEC-004** — `ksp-execution-lib` consomme fondamentalement `PreparedProgramExecution`, dépend de `ksp-program-api` et non de `ksp-program-lib`.
|
||||
- **KSP-EXEC-005** — `ksp-execution-lib` orchestre simulation, signature, submission, confirmation et retry de lifecycle à partir de primitives possédées par transport/wallet.
|
||||
- **KSP-EXEC-006** — Wallet/signers et transport/provider sont sélectionnés/fournis par la composition supérieure ; l'execution lib ne choisit pas arbitrairement ces ressources.
|
||||
- **KSP-EXEC-007** — Une approbation externe peut produire un état suspendu/reprenable sans dépendance de la policy/execution vers Tauri ou une UI.
|
||||
- **KSP-EXEC-008** — `ksp-execution-lib` ne persiste pas automatiquement son résultat et ne dépend pas du store.
|
||||
|
||||
## Transports
|
||||
|
||||
|
||||
Reference in New Issue
Block a user