diff --git a/Cargo.toml b/Cargo.toml index 5bf810f..eead8b9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 10 +# version: 11 [workspace] resolver = "3" members = ["crates/ksp-core-lib"] [workspace.package] -version = "0.0.3-pre.4" +version = "0.0.3-pre.5" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/deltas/0.0.3/pre.005.md b/deltas/0.0.3/pre.005.md new file mode 100644 index 0000000..0497687 --- /dev/null +++ b/deltas/0.0.3/pre.005.md @@ -0,0 +1,148 @@ + + + +# Delta 0.0.3-pre.005 + +## Base requise + +`v0.0.3-pre.004`. + +## Objectif + +Détailler `ksp-execution-policy-api` et `ksp-execution-lib`, fixer la séparation entre préparation Program, décision policy, wallet, transport et orchestration transactionnelle, puis formaliser `ksp-logging-lib` comme façade logging/tracing commune du runtime KSP. + +## Version Cargo + +`workspace.package.version` passe de : + +```text +0.0.3-pre.4 +``` + +à : + +```text +0.0.3-pre.5 +``` + +Le header de `Cargo.toml` passe de version 10 à 11. + +## Fichiers ajoutés + +- `docs/architecture/007-EXECUTION_AND_POLICY.md` +- `deltas/0.0.3/pre.005.md` + +## Fichiers modifiés + +- `Cargo.toml` +- `docs/architecture/000-README.md` +- `docs/architecture/002-LAYERS_AND_DEPENDENCIES.md` +- `docs/architecture/003-COMPONENT_CONTRACTS.md` +- `docs/architecture/004-COMPONENT_INVENTORY.md` +- `docs/architecture/005-DEPENDENCY_GRAPH.md` +- `docs/rules/RULES_DEPENDENCIES.md` +- `docs/rules/RULES_KSP.md` +- `docs/IDEAS.md` +- `docs/plans/001-V0_0_3_PLAN.md` +- `prompts/001-V0_1_X_START_PROMPT.md` + +## Fichiers supprimés + +Aucun. + +## Décisions principales + +### Policy + +- `ksp-execution-policy-api` est obligatoire explicitement pour toute exécution réelle via `ksp-execution-lib`. +- Aucun fallback permissif implicite n'est prévu. +- Une policy peut être consultée à plusieurs checkpoints lorsque des informations supplémentaires, notamment simulation, deviennent disponibles. +- Une policy décide/refuse/contraint et peut produire des requirements ; elle ne signe, ne simule, n'appelle le réseau ou l'UI elle-même. +- Une policy peut demander une approbation externe ; le cycle doit pouvoir être suspendu/repris sans dépendance vers Tauri/UI. + +### Execution + +`ksp-execution-lib` consomme fondamentalement `PreparedProgramExecution` et ne dépend pas de `ksp-program-lib`. + +Il orchestre : + +- policy checkpoints ; +- assemblage message/transaction ; +- simulation via transport ; +- signature via wallet ; +- submission ; +- confirmation ; +- retry de lifecycle ; +- suspension/reprise sur requirement externe. + +Wallet/signers et provider/transport sont sélectionnés/fournis par la composition supérieure. + +### Contraintes + +Trois sources sont distinguées : + +1. contraintes techniques Program, non négociables ; +2. options/contexte du caller ; +3. contraintes supplémentaires de policy. + +### Retry + +- retry technique d'un appel réseau identique -> transport ; +- retry qui nécessite reconstruction/resimulation/resignature/resubmission -> execution. + +### Store + +`ksp-execution-lib` ne dépend ni de `ksp-store-api` ni de `ksp-store-lib` et ne persiste pas automatiquement `ExecutionOutcome`. + +### Logging + +`ksp-logging-lib` est la façade commune de logging/tracing KSP. + +Elle importe directement et possède l'initialisation/configuration de : + +```text +tracing +tracing-appender +tracing-subscriber +``` + +Elle peut dépendre de `ksp-core-lib` pour `Error` / `Result`. + +`ksp-core-lib` n'a pas de dépendance logging requise. + +Les crates runtime KSP peuvent dépendre directement de `ksp-logging-lib` et utilisent sa façade pour : + +```text +error +warn +info +debug +trace +``` + +avec target/domain/champs structurés selon l'API finale. + +Les crates `*-api` purement déclaratives ne dépendent pas du logging par défaut. + +Une intégration Tauri peut exceptionnellement avoir besoin d'un plugin/d'une dépendance tracing au niveau framework, sans créer une seconde policy logging parallèle. + +La forme exacte de la façade (fonctions, macros ou combinaison) est reportée à l'implémentation de `ksp-logging-lib`. + +## Idées reportées + +- composition générique de plusieurs policies spécialisées ; +- mécanisme exact de reprise après approbation externe ; +- types Rust exacts des checkpoints/decisions/outcomes ; +- crates Solana précises pour message/transaction à sélectionner au moment de l'implémentation. + +## Suite + +`pre.006` peut maintenant traiter Data / Materializer / Store / Acquisition sans rouvrir les responsabilités Execution/Policy. + +## Validations + +- headers `file:` / `version:` vérifiés ; +- `Cargo.toml` parsé et version `0.0.3-pre.5` vérifiée ; +- présence de `007-EXECUTION_AND_POLICY.md` et de ses références vérifiée ; +- dépendances/interdictions Execution/Policy/Logging vérifiées dans le graphe et les règles ; +- aucune commande Cargo de build/test exécutée : ce delta reste documentaire et n'ajoute aucun code Rust fonctionnel. diff --git a/docs/IDEAS.md b/docs/IDEAS.md index 9559ae4..9002269 100644 --- a/docs/IDEAS.md +++ b/docs/IDEAS.md @@ -1,5 +1,5 @@ - + # 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. diff --git a/docs/architecture/000-README.md b/docs/architecture/000-README.md index 1ccc445..c5cf7d3 100644 --- a/docs/architecture/000-README.md +++ b/docs/architecture/000-README.md @@ -1,5 +1,5 @@ - + # 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. diff --git a/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md b/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md index d6b9c98..3fa0cbb 100644 --- a/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md +++ b/docs/architecture/002-LAYERS_AND_DEPENDENCIES.md @@ -1,5 +1,5 @@ - + # 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 diff --git a/docs/architecture/003-COMPONENT_CONTRACTS.md b/docs/architecture/003-COMPONENT_CONTRACTS.md index b369f80..e6461f7 100644 --- a/docs/architecture/003-COMPONENT_CONTRACTS.md +++ b/docs/architecture/003-COMPONENT_CONTRACTS.md @@ -1,5 +1,5 @@ - + # 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 diff --git a/docs/architecture/004-COMPONENT_INVENTORY.md b/docs/architecture/004-COMPONENT_INVENTORY.md index 28d1cb0..f1a0a5a 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # 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--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-` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques | -| Scenarios | `ksp-scenario--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---desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante | -| Specialized pipelines | `ksp-pipeline--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--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-` | job | N4 | À la demande | `0.4.x+` | metadata, quotes et autres travaux ponctuels/historiques | +| Scenarios | `ksp-scenario--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---desk-demo` | app | N4 | Retenu | `0.4.x+` | interface desktop appelant la crate scénario correspondante | +| Specialized pipelines | `ksp-pipeline--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 diff --git a/docs/architecture/005-DEPENDENCY_GRAPH.md b/docs/architecture/005-DEPENDENCY_GRAPH.md index 49342ad..cfa03e8 100644 --- a/docs/architecture/005-DEPENDENCY_GRAPH.md +++ b/docs/architecture/005-DEPENDENCY_GRAPH.md @@ -1,5 +1,5 @@ - + # 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--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. --- diff --git a/docs/architecture/007-EXECUTION_AND_POLICY.md b/docs/architecture/007-EXECUTION_AND_POLICY.md new file mode 100644 index 0000000..949c3b6 --- /dev/null +++ b/docs/architecture/007-EXECUTION_AND_POLICY.md @@ -0,0 +1,323 @@ + + + +# 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--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. diff --git a/docs/plans/001-V0_0_3_PLAN.md b/docs/plans/001-V0_0_3_PLAN.md index 8ad1831..73d64c6 100644 --- a/docs/plans/001-V0_0_3_PLAN.md +++ b/docs/plans/001-V0_0_3_PLAN.md @@ -1,5 +1,5 @@ - + # 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 diff --git a/docs/rules/RULES_DEPENDENCIES.md b/docs/rules/RULES_DEPENDENCIES.md index 5de7dd3..8cd5b9d 100644 --- a/docs/rules/RULES_DEPENDENCIES.md +++ b/docs/rules/RULES_DEPENDENCIES.md @@ -1,5 +1,5 @@ - + # 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--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 diff --git a/docs/rules/RULES_KSP.md b/docs/rules/RULES_KSP.md index 45f3f68..706c89b 100644 --- a/docs/rules/RULES_KSP.md +++ b/docs/rules/RULES_KSP.md @@ -1,5 +1,5 @@ - + # 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 diff --git a/prompts/001-V0_1_X_START_PROMPT.md b/prompts/001-V0_1_X_START_PROMPT.md index 2ab20d8..bb8c652 100644 --- a/prompts/001-V0_1_X_START_PROMPT.md +++ b/prompts/001-V0_1_X_START_PROMPT.md @@ -1,5 +1,5 @@ - + # Prompt de démarrage KSP 0.1.x @@ -33,7 +33,7 @@ Ces objectifs pourront être répartis entre plusieurs releases `0.1.N`. ## 5. Sources de vérité -Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `006`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`. +Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PROMPT_STRUCTURE.md`, les documents d'architecture `001` à `007`, le plan de version actif et les questions pertinentes de `docs/IDEAS.md`. ## 6. Décisions acquises pertinentes @@ -46,6 +46,7 @@ Relire au minimum `RULES.md`, `ROADMAP.md`, `docs/000-README.md`, `docs/rules/PR - Les applications restent des interfaces/compositions. - Les exécutables ne dépendent pas directement de crates Solana/protocoles externes. - `ksp-core-lib` doit posséder les Program IDs fondamentaux et le type d'erreur commun. +- `ksp-logging-lib` est la façade KSP propriétaire de `tracing`, `tracing-appender` et `tracing-subscriber`; elle peut dépendre de Core pour `Error` / `Result`, tandis que Core n'a pas de dépendance logging requise. - Les dépendances basses suivent le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md` ; N1 ne doit pas dépendre de ses consommateurs supérieurs. - KSP évite les générations anciennes/dupliquées évitables de dépendances fondamentales ; toute contrainte de version non actuelle doit être motivée par un besoin réel. - Les règles fines de naming/arborescence/API publique seront définies à partir des premières APIs réelles.