From 544e0351b804c4d2be463b83d7899259fce6a783 Mon Sep 17 00:00:00 2001 From: SinuS Von SifriduS Date: Fri, 14 Aug 2026 08:57:39 +0200 Subject: [PATCH] v0.0.3-pre.003 --- Cargo.toml | 4 +- ROADMAP.md | 8 +- deltas/0.0.3/pre.003.md | 182 ++++++ docs/IDEAS.md | 20 +- docs/architecture/000-README.md | 7 +- docs/architecture/003-COMPONENT_CONTRACTS.md | 20 +- docs/architecture/004-COMPONENT_INVENTORY.md | 102 +-- docs/architecture/005-DEPENDENCY_GRAPH.md | 637 +++++++++++++++++++ docs/plans/001-V0_0_3_PLAN.md | 97 +-- docs/rules/RULES_DEPENDENCIES.md | 60 +- docs/rules/RULES_KSP.md | 15 +- prompts/001-V0_1_X_START_PROMPT.md | 5 +- 12 files changed, 1033 insertions(+), 124 deletions(-) create mode 100644 deltas/0.0.3/pre.003.md create mode 100644 docs/architecture/005-DEPENDENCY_GRAPH.md diff --git a/Cargo.toml b/Cargo.toml index 6f5f876..3255600 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,12 +1,12 @@ # file: Cargo.toml -# version: 8 +# version: 9 [workspace] resolver = "3" members = ["crates/ksp-core-lib"] [workspace.package] -version = "0.0.3-pre.2" +version = "0.0.3-pre.3" edition = "2024" license = "MIT" repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project" diff --git a/ROADMAP.md b/ROADMAP.md index d68c717..f31cd02 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,10 +1,12 @@ - + # Roadmap KSP Le roadmap décrit les objectifs à atteindre et les grandes étapes prévues pour y parvenir. Une série `X.Y.x` regroupe une famille fonctionnelle de travaux ; elle peut contenir plusieurs releases concrètes et plusieurs sessions. +Les décisions architecturales négatives ou de prudence n'apparaissent pas comme des tâches à cocher. Elles sont conservées dans les règles et documents d'architecture. + ## Légende - `[ ]` — prévu / non commencé ; @@ -41,8 +43,8 @@ Regrouper les releases consacrées aux fondations N1. La série n'est pas destin - [ ] Introduire `ksp-wallet-lib` et `ksp-app-wallet-desk`. - [ ] Développer la première surface utile de `ksp-interface-lib`. - [ ] Introduire `ksp-program-api` puis `ksp-program-lib`. -- [ ] Étudier/introduire `ksp-execution-policy-api` et `ksp-execution-lib` selon le graphe validé. -- [ ] Ne pas créer `ksp-onchain-transport-api` ni `ksp-wallet-api` sans nouveau besoin concret. +- [ ] Définir `ksp-execution-policy-api` comme contrat de policy commun à plusieurs contextes. +- [ ] Introduire `ksp-execution-lib` lorsque le premier cycle d'exécution réel justifie l'orchestration programme/policy/wallet/transport. - [ ] Introduire `ksp-offchain-transport-lib` seulement au premier besoin réel. ## 0.3.x — Données, stockage et acquisition raw diff --git a/deltas/0.0.3/pre.003.md b/deltas/0.0.3/pre.003.md new file mode 100644 index 0000000..82905a9 --- /dev/null +++ b/deltas/0.0.3/pre.003.md @@ -0,0 +1,182 @@ + + + +# Delta 0.0.3-pre.003 + +## Base requise + +`v0.0.3-pre.002`. + +## Objectif + +Formaliser le graphe de dépendances KSP, corriger l'inventaire `pre.002` lorsque le graphe révèle une frontière plus propre et éliminer les dépendances susceptibles de créer des cycles ou de mélanger sémantique, I/O et persistence. + +## Version Cargo + +`workspace.package.version` passe de : + +```text +0.0.3-pre.2 +``` + +à : + +```text +0.0.3-pre.3 +``` + +Le header de `Cargo.toml` passe de version 8 à 9. + +## Fichiers ajoutés + +- `docs/architecture/005-DEPENDENCY_GRAPH.md` +- `deltas/0.0.3/pre.003.md` + +## Fichiers modifiés + +- `Cargo.toml` +- `ROADMAP.md` +- `docs/architecture/000-README.md` +- `docs/architecture/003-COMPONENT_CONTRACTS.md` +- `docs/architecture/004-COMPONENT_INVENTORY.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. + +## Corrections du roadmap + +La ligne : + +```text +Ne pas créer ksp-onchain-transport-api ni ksp-wallet-api sans nouveau besoin concret +``` + +est supprimée des tâches à cocher. + +Il s'agit d'une décision architecturale, conservée dans les règles et le graphe, pas d'un livrable. + +## Décisions principales + +### Program + +```text +ksp-program-api + -> core/interface + +ksp-program-lib + -> ksp-program-api +``` + +Program reste indépendant du wallet, du transport, du store et des materializers. + +### Execution / Policy + +`ksp-execution-policy-api` et `ksp-execution-lib` passent de candidats forts à composants retenus. + +`ksp-execution-lib` dépend de : + +```text +ksp-program-api +ksp-execution-policy-api +ksp-wallet-lib +ksp-onchain-transport-lib +``` + +Il ne dépend pas de `ksp-program-lib`. + +Les implémentations Program officielles ou externes restent substituables derrière `ksp-program-api`. + +### Materializer + +`ksp-materializer-api` peut dépendre de `ksp-program-api`. + +`ksp-materializer-api` et `ksp-materializer-lib` ne dépendent pas du store. + +### Store + +`ksp-store-api` reste indépendant de Program, Materializer et Transport. + +`ksp-store-lib` implémente `ksp-store-api` avec PostgreSQL comme référence. + +Les modèles persistants appartiennent au store ; les workers/jobs effectuent les conversions depuis les modèles de transport/processing. + +Aucun `ksp-data-api` global n'est introduit. + +### Transport + +`ksp-onchain-transport-lib` ne dépend pas du store. + +Les providers normalisent leurs réponses dans des modèles de transport homogènes, ensuite convertis explicitement par `ksp-worker-raw-retriever`. + +### Workers / Jobs + +`ksp-worker-api` et `ksp-job-api` restent des lifecycle APIs séparées. + +`ksp-worker-control-lib` dépend de `ksp-worker-api` et ne contrôle pas les jobs. + +Aucune `ksp-job-control-lib` n'est prévue. + +### Notifications + +`ksp-store-api` devient le propriétaire retenu du contrat canonique de notification lorsqu'une donnée persistée est disponible. + +Le contrat reste indépendant du producteur et du mécanisme de diffusion. + +## Frontières de conversion retenues + +```text +transport model + -> worker/job acquisition + -> store raw DTO + +store raw DTO + -> core processor + -> program API/lib + -> store Core DTO + +store Core DTO + -> materializer worker + -> materializer API/lib + -> store materialization/projection DTO +``` + +Ces conversions explicites empêchent les dépendances croisées entre bibliothèques basses. + +## Questions reportées + +### `pre.004` + +- types exacts decoder/executor ; +- opération préparée ; +- policy API détaillée ; +- cycle exact de `ksp-execution-lib` ; +- conformité wire et historique/deprecated. + +### `pre.005` + +- modèles persistants raw/Core/materialization/projection ; +- materializer API détaillée ; +- notifications et diffusion ; +- replay/provenance/idempotence ; +- rôle précis des workers de matérialisation. + +### `pre.006` + +- managers/processus/IPC ; +- norme scenarios ; +- orchestration globale ; +- pipelines spécialisés. + +## Validations + +- headers `file:` / `version:` vérifiés sur tous les fichiers Markdown livrés ; +- `Cargo.toml` parsé avec succès et version vérifiée à `0.0.3-pre.3` ; +- références internes vers `005-DEPENDENCY_GRAPH.md` vérifiées ; +- anciennes références à la fausse tâche roadmap vérifiées absentes ; +- aucune commande Cargo exécutée : l'archive delta ne contient pas le workspace complet et ne modifie aucun code Rust. diff --git a/docs/IDEAS.md b/docs/IDEAS.md index f00e5e5..e52b4a7 100644 --- a/docs/IDEAS.md +++ b/docs/IDEAS.md @@ -1,5 +1,5 @@ - + # Idées à explorer @@ -26,9 +26,9 @@ Premiers couples retenus : program, materializer et store. Les APIs worker/job s ### Execution policy API -**Status :** En exploration — candidat fort +**Status :** Transférée vers une décision/règle -Étudier `ksp-execution-policy-api` comme contrat commun d'autorisation/safety/policy d'une exécution. +`ksp-execution-policy-api` est retenu comme contrat commun d'autorisation/safety/policy d'une exécution. Le contrat doit permettre des implémentations différentes selon le contexte, par exemple scenario Devnet, application générale ou futur produit trading. @@ -36,11 +36,11 @@ L'UI sélectionne/injecte une implémentation réutilisable ; elle ne doit pas d ### Execution orchestration -**Status :** En exploration — candidat fort +**Status :** Transférée vers une décision/règle -Étudier `ksp-execution-lib` comme orchestration spécialisée entre programme, policy, wallet et transport, plutôt qu'une dépendance directe de `ksp-program-lib` vers wallet/transport. +`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`. -Le graphe exact est reporté à `0.0.3-pre.003`. +Les types exacts d'opération préparée et de policy restent à définir en `0.0.3-pre.004`. ### Scenarios : norme avant API @@ -80,6 +80,14 @@ Définir avec les premières crates fonctionnelles les conventions d'arborescenc Aucune `ksp-onchain-transport-api` séparée n'est prévue. +### Modèles communs inter-domaines + +**Status :** À explorer avec l'implémentation + +Aucun `ksp-data-api` global n'est prévu actuellement. Les modèles appartiennent à leur responsabilité (transport, program, materializer, store) et les composants de composition réalisent les conversions explicites. + +Réévaluer seulement si les premières implémentations montrent une duplication réellement nuisible impossible à résoudre sans contrat commun supplémentaire. + ### Off-chain volontairement hétérogène **Status :** Retenue diff --git a/docs/architecture/000-README.md b/docs/architecture/000-README.md index a06bb67..35b5d5c 100644 --- a/docs/architecture/000-README.md +++ b/docs/architecture/000-README.md @@ -1,5 +1,5 @@ - + # Architecture KSP @@ -20,6 +20,7 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas. 1. [`001-PROJECT_OBJECTIVES.md`](001-PROJECT_OBJECTIVES.md) — finalité, objectifs produits et non-objectifs architecturaux ; 2. [`002-LAYERS_AND_DEPENDENCIES.md`](002-LAYERS_AND_DEPENDENCIES.md) — couches conceptuelles, sens des dépendances et responsabilités des exécutables ; 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) — premier inventaire des domaines, APIs, bibliothèques, workers, jobs, scénarios et applications candidates. +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. -L'inventaire `004` est volontairement révisable pendant `0.0.3-pre.003` lorsque le graphe de dépendances révélera des frontières à corriger. +`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/003-COMPONENT_CONTRACTS.md b/docs/architecture/003-COMPONENT_CONTRACTS.md index 36a3acf..533233b 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). +L'inventaire détaillé courant est maintenu dans [`004-COMPONENT_INVENTORY.md`](004-COMPONENT_INVENTORY.md) et le graphe autorisé/interdit dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md). ## Convention API / implémentation @@ -45,7 +45,7 @@ Aucune API commune worker+job n'est prévue. `ksp-program-lib` ne possède pas la politique de sécurité/autorisation d'un produit. -La direction retenue pour étude est un contrat public séparé : +Le contrat public séparé suivant est retenu : ```text ksp-execution-policy-api @@ -57,7 +57,7 @@ Les applications UI sélectionnent/injectent une implémentation réutilisable a ## Execution orchestration -`ksp-execution-lib` devient un candidat fort de pipeline/orchestrateur spécialisé pour relier : +`ksp-execution-lib` est retenu comme pipeline/orchestrateur spécialisé pour relier : - la préparation/sémantique programme ; - une implémentation de `ksp-execution-policy-api` ; @@ -66,7 +66,17 @@ Les applications UI sélectionnent/injectent une implémentation réutilisable a Le but est d'éviter que `ksp-program-lib` dépende directement du wallet/transport uniquement pour réaliser le cycle réseau/signature. -Le graphe exact reste à valider dans `pre.003`. +`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`. + +## Frontière materializer / store + +`ksp-materializer-api` peut dépendre de `ksp-program-api` pour consommer des contrats de processing communs. + +`ksp-materializer-lib` reste une bibliothèque de transformation et ne dépend ni de `ksp-store-api` ni de `ksp-store-lib`. + +`ksp-store-api` possède les DTO/contrats persistants et reste indépendant des APIs Program/Materializer. Les workers de processing convertissent explicitement entre modèles runtime et modèles persistants. + +Cette règle évite d'introduire un `ksp-data-api` monolithique uniquement pour partager des modèles entre couches. ## Transport on-chain diff --git a/docs/architecture/004-COMPONENT_INVENTORY.md b/docs/architecture/004-COMPONENT_INVENTORY.md index 780762a..5e635de 100644 --- a/docs/architecture/004-COMPONENT_INVENTORY.md +++ b/docs/architecture/004-COMPONENT_INVENTORY.md @@ -1,5 +1,5 @@ - + # Inventaire initial des composants KSP @@ -9,7 +9,7 @@ Ce document constitue le premier inventaire architectural de `0.0.3-pre.002`. Il répond principalement à la question : **quel composant possède quelle responsabilité ?** -Il ne fige pas encore le graphe exact des dépendances. `0.0.3-pre.003` doit explicitement pouvoir corriger cet inventaire lorsque l'étude des dépendances montre qu'une API, une bibliothèque ou une frontière doit être déplacée, séparée ou supprimée. +Le premier inventaire a été produit en `0.0.3-pre.002`. `0.0.3-pre.003` l'a corrigé à partir du graphe formalisé dans [`005-DEPENDENCY_GRAPH.md`](005-DEPENDENCY_GRAPH.md). Les détails internes des APIs restent toutefois révisables dans les prereleases spécialisées suivantes. ## Statuts @@ -21,40 +21,40 @@ Il ne fige pas encore le graphe exact des dépendances. `0.0.3-pre.003` doit exp ## 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 decoder/executor et types associés | -| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés | -| Execution policy | `ksp-execution-policy-api` | API | N3 contrat | Candidat fort | `0.2.x–0.4.x` | contrat public permettant à chaque contexte d'autoriser/refuser/contraindre une exécution | -| Execution orchestration | `ksp-execution-lib` | lib | N3 | Candidat fort | `0.2.x–0.4.x` | orchestration spécialisée entre opération préparée, policy, wallet et transport | -| 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 | Candidat fort | `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` | 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 decoder/executor et types associés | +| Program impl. | `ksp-program-lib` | lib | N2 | Retenu | `0.2.x+` | decoders/executors officiels intégrés | +| 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 | ## APIs séparées retenues @@ -77,7 +77,7 @@ Aucune API commune worker+job n'est prévue. ## Execution policy et orchestration -### Direction retenue pour étude en `pre.003` +### Direction retenue après `pre.003` 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 : @@ -106,7 +106,7 @@ Une application UI ne doit pas enfouir cette logique dans ses commandes ou compo 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. -Le graphe exact `ksp-execution-lib -> ksp-program-api` ou `ksp-program-lib`, ainsi que la forme des plans/opérations préparées, est explicitement reporté à `pre.003/pre.004`. +`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`. ## Transport on-chain @@ -260,12 +260,22 @@ Chaque application appelle la crate `ksp-scenario--lib` correspondante e Des pipelines spécialisés peuvent être créés à la demande lorsqu'un flux concret possède assez de logique réutilisable pour justifier sa propre frontière. Leur forme n'est pas nécessairement une bibliothèque : certains pourront être workers, jobs ou composants spécialisés. -## Questions explicitement reportées à `pre.003` +## Corrections issues de `pre.003` -- dépendance exacte de `ksp-execution-lib` vers `ksp-program-api` et/ou `ksp-program-lib` ; -- forme du contrat entre program preparation, execution policy, wallet et transport ; -- emplacement exact des modèles communs nécessaires à l'exécution ; -- types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ; -- dépendances autorisées de `ksp-materializer-api` et `ksp-store-api` ; -- risque de cycles entre program, materializer, store, execution et control ; -- position exacte des notifications de données dans le graphe. +Le graphe confirme les principes suivants : + +- Program et Materializer restent indépendants du store et des I/O réseau ; +- `ksp-execution-policy-api` et `ksp-execution-lib` sont retenus ; +- `ksp-execution-lib` consomme `ksp-program-api`, pas l'implémentation officielle `ksp-program-lib` ; +- `ksp-materializer-api` peut dépendre de `ksp-program-api`, mais ni Materializer API/lib ni Store API/lib ne se dépendent mutuellement ; +- les workers/jobs spécialisés réalisent les conversions explicites entre modèles de transport, processing et persistence ; +- aucun `ksp-data-api` global n'est introduit ; +- `ksp-worker-control-lib` est retenu comme gouvernance workers réutilisable ; aucune `ksp-job-control-lib` n'est retenue. + +## Questions reportées aux prereleases suivantes + +- `pre.004` : forme exacte du contrat entre program preparation, execution policy, wallet et transport ; +- `pre.004` : types publics précis de `ksp-program-api` et policy ; +- `pre.005` : types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ; +- `pre.005` : modèles materializer/store, notifications, replay et provenance ; +- `pre.006` : managers/apps/processus/IPC, norme des scenarios et orchestrateur futur. diff --git a/docs/architecture/005-DEPENDENCY_GRAPH.md b/docs/architecture/005-DEPENDENCY_GRAPH.md new file mode 100644 index 0000000..9b61242 --- /dev/null +++ b/docs/architecture/005-DEPENDENCY_GRAPH.md @@ -0,0 +1,637 @@ + + + +# Graphe de dépendances KSP + +## Objet + +Ce document constitue la sortie principale de `0.0.3-pre.003`. + +Il répond à la question : **quels composants peuvent dépendre de quels autres composants, et où doivent se produire la composition, l'I/O et les conversions de modèles ?** + +Convention des graphes : + +```text +A -> B +``` + +signifie : **A peut dépendre de B**. + +Le graphe exprime une direction architecturale. Une dépendance autorisée n'est pas obligatoire si l'implémentation peut rester plus faible. + +## Principes structurants + +### 1. APIs sous les implémentations + +Une crate `ksp--api` est placée sous les implémentations de son domaine. + +```text +implementation -> domain-api +``` + +Une API publique ne dépend pas de son implémentation officielle. + +### 2. Transformations séparées de l'I/O + +Les bibliothèques de sémantique/transformation comme `ksp-program-lib` et `ksp-materializer-lib` ne deviennent pas propriétaires : + +- du transport réseau ; +- du wallet ; +- du backend PostgreSQL ; +- du lifecycle d'un worker/job. + +Les workers, jobs, scenarios et pipelines spécialisés composent ces capacités lorsqu'ils ont réellement besoin d'I/O. + +### 3. Modèles de domaine distincts des DTO persistants + +KSP ne crée pas actuellement un `ksp-data-api` global. + +Chaque frontière possède les modèles nécessaires à sa responsabilité : + +- transport : modèles homogènes de transport ; +- program : contrats de décodage/opération préparée ; +- materializer : entrées/sorties de matérialisation ; +- store : modèles persistants et références de données persistées. + +La conversion entre ces modèles est explicite dans la couche qui relie les deux responsabilités, principalement les workers/jobs spécialisés. + +### 4. Composition supérieure pour l'exécution + +`ksp-program-lib` ne dépend pas de `ksp-wallet-lib` ou de `ksp-onchain-transport-lib`. + +Le cycle signature/simulation/envoi/confirmation est composé au-dessus, par `ksp-execution-lib`. + +### 5. Workers et jobs restent deux familles + +`ksp-worker-api` et `ksp-job-api` n'ont pas de parent lifecycle commun. + +Un orchestrateur futur peut consommer les deux familles séparément sans les fusionner. + +--- + +# Graphe fondations N1 + +```text +ksp-core-lib + +ksp-config-lib -> ksp-core-lib +ksp-logging-lib -> ksp-core-lib +ksp-interface-lib -> ksp-core-lib +``` + +`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. + +--- + +# Graphe Program + +```text +ksp-program-api + -> ksp-core-lib + -> ksp-interface-lib + +ksp-program-lib + -> ksp-program-api + -> ksp-interface-lib + -> ksp-core-lib +``` + +## Frontière de `ksp-program-api` + +`ksp-program-api` doit porter les contrats publics nécessaires à une implémentation externe de decoder/executor. + +Il est également le propriétaire candidat du **contrat d'opération préparée** produit par la sémantique programme et consommé par la couche d'exécution. + +Noms exacts à définir en `pre.004`, par exemple conceptuellement : + +```text +PreparedProgramOperation +ProgramExecutionPlan +``` + +Le choix du nom/type final n'est pas décidé ici. + +## Interdictions Program + +```text +ksp-program-api -X-> ksp-wallet-lib +ksp-program-api -X-> ksp-onchain-transport-lib +ksp-program-api -X-> ksp-store-api +ksp-program-api -X-> ksp-materializer-api + +ksp-program-lib -X-> ksp-wallet-lib +ksp-program-lib -X-> ksp-onchain-transport-lib +ksp-program-lib -X-> ksp-store-api +ksp-program-lib -X-> ksp-store-lib +ksp-program-lib -X-> ksp-materializer-lib +ksp-program-lib -X-> ksp-execution-lib +``` + +Le decoder/executor de programme reste donc testable sans réseau, wallet ou base de données. + +--- + +# Graphe Execution / Policy + +`ksp-execution-policy-api` et `ksp-execution-lib` sont retenus comme composants. + +```text +ksp-execution-policy-api + -> ksp-program-api + -> ksp-core-lib + +ksp-execution-lib + -> ksp-program-api + -> ksp-execution-policy-api + -> ksp-wallet-lib + -> ksp-onchain-transport-lib + -> ksp-core-lib +``` + +## Décision importante + +`ksp-execution-lib` **ne dépend pas de `ksp-program-lib`**. + +Il consomme le contrat public de `ksp-program-api` et reçoit : + +- 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 forme exacte sera décidée en `pre.004`. + +Cette règle permet : + +```text +ksp-program-lib ------------------\ +external-program-implementation ---+--> ksp-program-api --> execution +other-compatible-implementation ---/ +``` + +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. + +--- + +# Graphe Wallet + +```text +ksp-wallet-lib + -> ksp-core-lib +``` + +`ksp-wallet-lib` peut consommer config/logging si nécessaire à son implémentation, sans que ces dépendances deviennent partie obligatoire du contrat wallet. + +Interdictions : + +```text +ksp-wallet-lib -X-> ksp-program-lib +ksp-wallet-lib -X-> ksp-execution-lib +ksp-wallet-lib -X-> ksp-store-lib +``` + +Le wallet fournit les capacités de clés/signature ; il n'orchestre pas une opération Solana. + +--- + +# Graphe Transport + +## On-chain + +```text +ksp-onchain-transport-lib + -> ksp-core-lib +``` + +Il peut consommer config/logging lorsque nécessaire. + +Il peut posséder plusieurs familles internes : + +```text +HTTP RPC +WS RPC +Helius advanced +Yellowstone +... +``` + +sans créer `ksp-onchain-transport-api`. + +### Modèles homogènes + +Chaque famille provider convertit ses réponses propriétaires vers des modèles KSP homogènes **à l'intérieur de la frontière transport**. + +Exemple conceptuel : + +```text +Solana RPC ------\ +Helius -----------+--> transport raw model +Yellowstone ------/ +``` + +Ces modèles : + +- sont indépendants du store ; +- conservent le raw et la provenance nécessaire ; +- sont faciles à convertir vers les modèles persistants. + +Interdiction ferme : + +```text +ksp-onchain-transport-lib -X-> ksp-store-api +ksp-onchain-transport-lib -X-> ksp-store-lib +``` + +## Off-chain + +```text +ksp-offchain-transport-lib + -> ksp-core-lib +``` + +Config/logging sont autorisés selon le besoin. + +La crate reste volontairement hétérogène. Aucun `ksp-offchain-transport-api` global n'est introduit. + +--- + +# Graphe Materialization + +```text +ksp-materializer-api + -> ksp-core-lib + -> ksp-program-api + +ksp-materializer-lib + -> ksp-materializer-api + -> ksp-program-api + -> ksp-core-lib +``` + +`ksp-interface-lib` peut être consommée par `ksp-materializer-lib` lorsqu'une matérialisation a réellement besoin d'un contrat wire déjà possédé par KSP, mais ne doit pas devenir une dépendance obligatoire de toute matérialisation. + +## Décision importante + +Ni `ksp-materializer-api` ni `ksp-materializer-lib` ne dépendent du store. + +```text +ksp-materializer-api -X-> ksp-store-api +ksp-materializer-lib -X-> ksp-store-api +ksp-materializer-lib -X-> ksp-store-lib +``` + +Une matérialisation transforme des données ; le worker/job/pipeline spécialisé persiste le résultat. + +Cette séparation permet également de tester un materializer externe sans PostgreSQL. + +--- + +# Graphe Store + +```text +ksp-store-api + -> ksp-core-lib + +ksp-store-lib + -> ksp-store-api + -> ksp-core-lib +``` + +`ksp-store-lib` peut dépendre de config/logging et contient PostgreSQL comme implémentation de référence. + +## Indépendance du store + +Le store ne dépend pas des implémentations Program/Materializer/Transport : + +```text +ksp-store-api -X-> ksp-program-api +ksp-store-api -X-> ksp-materializer-api +ksp-store-api -X-> ksp-onchain-transport-lib + +ksp-store-lib -X-> ksp-program-lib +ksp-store-lib -X-> ksp-materializer-lib +ksp-store-lib -X-> ksp-onchain-transport-lib +``` + +`ksp-store-api` définit les DTO/contrats persistants nécessaires aux niveaux durables sans imposer les modèles runtime des processors. + +## Notifications de données persistées + +`ksp-store-api` est retenu comme propriétaire du contrat canonique de notification lorsqu'il signifie : + +> une donnée persistée de telle catégorie est disponible. + +Le même contrat est utilisé quelle que soit l'origine : + +```text +live worker ----\ +backfill job ----+--> persisted data notification +import ----------/ +``` + +Le mécanisme de diffusion reste hors du contrat : + +```text +channel +LISTEN/NOTIFY +IPC +broker +... +``` + +Le mode de transport concret sera détaillé en `pre.005`. + +--- + +# Graphe lifecycle Worker + +```text +ksp-worker-api + -> ksp-core-lib + +ksp-worker-control-lib + -> ksp-worker-api + -> ksp-core-lib +``` + +`ksp-worker-control-lib` ne dépend pas des workers concrets. Il fournit une gouvernance réutilisable au-dessus de l'API. + +Les managers/apps/orchestrateurs composent les implémentations concrètes avec cette bibliothèque. + +Interdictions : + +```text +ksp-worker-api -X-> ksp-job-api +ksp-worker-control-lib -X-> ksp-job-api +``` + +Le contrôle des jobs ne fuit pas dans la gouvernance workers. + +--- + +# Graphe lifecycle Job + +```text +ksp-job-api + -> ksp-core-lib +``` + +Aucune `ksp-job-control-lib` n'est prévue actuellement. + +Interdictions : + +```text +ksp-job-api -X-> ksp-worker-api +ksp-job-api -X-> ksp-worker-control-lib +``` + +Un futur orchestrateur peut utiliser workers et jobs séparément sans créer de superclass lifecycle commune. + +--- + +# Graphe des composants concrets d'acquisition/processing + +Les dépendances ci-dessous décrivent la composition attendue. Les détails de processus/IPC seront approfondis plus tard. + +## `ksp-worker-raw-retriever` + +```text +ksp-worker-raw-retriever + -> ksp-worker-api + -> ksp-config-lib + -> ksp-onchain-transport-lib + -> ksp-store-api + -> ksp-store-lib + -> ksp-logging-lib +``` + +Responsabilité de conversion : + +```text +transport raw model + | + v +store raw persistence model +``` + +Cette conversion appartient au worker d'acquisition, pas au transport ni au store. + +## `ksp-job-backfill` + +```text +ksp-job-backfill + -> ksp-job-api + -> ksp-config-lib + -> ksp-onchain-transport-lib + -> ksp-store-api + -> ksp-store-lib + -> ksp-logging-lib +``` + +Il utilise la même famille de DTO raw persistants et la même notification de données persistées que W1. + +## `ksp-worker-core-processor` + +```text +ksp-worker-core-processor + -> ksp-worker-api + -> ksp-program-api + -> ksp-program-lib + -> ksp-store-api + -> ksp-store-lib + -> ksp-config-lib + -> ksp-logging-lib +``` + +Il effectue la conversion explicite : + +```text +store raw DTO + | + v +program decode input + | + v +program canonical/decode output + | + v +store Core DTO +``` + +`ksp-program-lib` ne connaît donc pas le store. + +## `ksp-worker-generic-materializer` + +```text +ksp-worker-generic-materializer + -> ksp-worker-api + -> ksp-materializer-api + -> ksp-materializer-lib + -> ksp-store-api + -> ksp-store-lib + -> ksp-config-lib + -> ksp-logging-lib +``` + +La frontière exacte des entrées/sorties génériques sera détaillée en `pre.005`. + +## `ksp-worker-domain-projector` + +```text +ksp-worker-domain-projector + -> ksp-worker-api + -> ksp-materializer-api + -> ksp-materializer-lib + -> ksp-store-api + -> ksp-store-lib + -> ksp-config-lib + -> ksp-logging-lib +``` + +Son nom reste provisoire. + +Il est propriétaire de la composition entre résultats de matérialisation spécialisée et projections persistantes par domaine ; `ksp-materializer-lib` reste indépendant du backend. + +--- + +# Scenarios et applications demo + +Une crate scénario peut composer les capacités nécessaires à son domaine : + +```text +ksp-scenario--lib + -> ksp-program-api + -> ksp-program-lib + -> ksp-execution-policy-api + -> ksp-execution-lib + -> ksp-wallet-lib + -> ksp-onchain-transport-lib + -> ksp-config-lib +``` + +Toutes ces dépendances ne sont pas obligatoires pour chaque scénario. + +La crate scénario peut implémenter une policy Devnet adaptée à son besoin. + +L'application correspondante reste une interface : + +```text +ksp-app-scenario--devnet-desk-demo + -> ksp-scenario--lib +``` + +Elle peut dépendre de bibliothèques KSP d'interface/configuration strictement nécessaires à son UI, mais ne réimplémente ni scénario ni policy métier. + +--- + +# Orchestrateur futur + +Le futur orchestrateur est au-dessus des contrôles spécialisés. + +Conceptuellement : + +```text +orchestrator + -> ksp-worker-control-lib + -> ksp-job-api # séparément, si coordination de jobs nécessaire + -> autres contrôles spécialisés au besoin +``` + +Cette dépendance simultanée ne crée pas d'API lifecycle commune. + +L'orchestrateur coordonne ; il ne fusionne pas les modèles worker/job. + +--- + +# Dépendances explicitement non retenues + +Les composants suivants ne sont pas introduits dans le graphe actuel : + +```text +ksp-api-lib +ksp-onchain-transport-api +ksp-offchain-transport-api +ksp-wallet-api +ksp-scenario-api +ksp-job-control-lib +ksp-pipeline-lib +ksp-data-api +``` + +Ils pourront être réévalués uniquement si un besoin concret démontre que la frontière actuelle ne suffit plus. + +--- + +# Contrôle des cycles + +Le graphe impose notamment : + +```text +core + <- interface + <- program-api + <- materializer-api + +store-api + <- store-lib + +worker-api + <- worker-control + +job-api + <- concrete jobs +``` + +et interdit toute boucle inverse depuis les couches basses vers leurs consommateurs. + +Les conversions entre Program/Materializer/Store ne sont pas résolues par des dépendances croisées mais par des composants de composition explicites. + +--- + +# Questions reportées + +`pre.004` doit détailler : + +- noms/types exacts des entrées/sorties de `ksp-program-api` ; +- forme exacte de l'opération préparée ; +- appel/injection entre program implementation et `ksp-execution-lib` ; +- contrat exact de `ksp-execution-policy-api` ; +- frontière entre préparation, policy, simulation, signature, envoi et confirmation. + +`pre.005` doit détailler : + +- DTO raw/Core/materialization/projection du store ; +- entrées/sorties `ksp-materializer-api` ; +- conversion Core runtime <-> store Core ; +- notifications et transport de notifications ; +- niveaux durables/replay/idempotence/provenance ; +- rôle précis des deux workers de matérialisation. + +`pre.006` doit détailler : + +- managers spécialisés ; +- processus/IPC éventuels ; +- norme des scenarios ; +- apps demo ; +- orchestrateur futur et pipelines spécialisés. diff --git a/docs/plans/001-V0_0_3_PLAN.md b/docs/plans/001-V0_0_3_PLAN.md index f62d9c9..5e9fd13 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 @@ -9,79 +9,92 @@ Transformer le brainstorming KSP en architecture, règles, inventaire et plan su ## État courant -`pre.001` est considérée stabilisée et commitée comme `v0.0.3-pre.001`. +- `pre.001` — base de planification stabilisée et commitée ; +- `pre.002` — inventaire initial des composants ; +- `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition. -`pre.002` produit le premier inventaire des composants et responsabilités. Cet inventaire est volontairement révisable dans `pre.003` lorsque le graphe de dépendances sera étudié. +La prochaine tranche prévue est `pre.004`, consacrée à Program/Wire/Execution. ## Décisions structurantes actuelles -- `0.1.x`, `0.2.x`, etc. sont des **séries fonctionnelles**, pas des unités de session. -- Chaque release concrète d'une série doit être dimensionnée séparément pour une session raisonnable. +- `0.1.x`, `0.2.x`, etc. sont des séries fonctionnelles, pas des unités de session. +- Chaque release concrète d'une série est dimensionnée séparément. - Les bibliothèques d'implémentation utilisent `ksp--lib` ; les contrats publics extensibles utilisent `ksp--api`. -- Program, materializer et store ont un couple API/implémentation séparé. -- Workers et jobs ont des lifecycle APIs distinctes. -- `ksp-worker-raw-retriever` réalise uniquement l'acquisition live/quasi-live raw. -- Le processing futur est séparé en `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector` (nom du dernier provisoire). +- Program, Materializer et Store ont un couple API/implémentation séparé. +- Workers et jobs ont des lifecycle APIs distinctes, sans parent commun. +- `ksp-worker-raw-retriever` réalise uniquement l'acquisition raw live/quasi-live. - `ksp-job-backfill` réalise l'acquisition historique à la demande. -- `ksp-worker-control-lib` est destiné à être réutilisé par managers/apps/orchestrateur ; aucune `ksp-job-control-lib` n'est prévue sans besoin concret. -- `ksp-execution-policy-api` et `ksp-execution-lib` sont des candidats forts pour séparer policy et orchestration d'exécution de `ksp-program-lib`. -- Pas de `ksp-onchain-transport-api`, `ksp-offchain-transport-api` ou `ksp-wallet-api` dans l'architecture actuelle. -- `ksp-onchain-transport-lib` expose des modèles de transport homogènes mais indépendants du store. -- Pas de `ksp-scenario-api` pour l'instant : privilégier une norme souple de scénarios spécialisés. -- Pas de `ksp-pipeline-lib` monolithique ; pipelines spécialisés uniquement à la demande. +- Le processing futur est séparé entre `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector`. +- `ksp-worker-control-lib` est la gouvernance commune des workers ; aucune `ksp-job-control-lib` n'est prévue actuellement. +- `ksp-execution-policy-api` est retenu. +- `ksp-execution-lib` est retenu comme orchestration spécialisée et dépend de `ksp-program-api`, pas de `ksp-program-lib`. +- `ksp-program-lib` ne dépend ni du wallet ni du transport. +- `ksp-materializer-lib` ne dépend pas du store. +- `ksp-store-api` reste indépendant de Program/Materializer/Transport. +- Les workers/jobs spécialisés convertissent explicitement les modèles entre transport, processing et persistence. +- `ksp-store-api` possède les notifications canoniques de données persistées ; leur transport concret reste séparé. +- Aucun `ksp-data-api`, `ksp-pipeline-lib`, `ksp-scenario-api`, `ksp-onchain-transport-api`, `ksp-offchain-transport-api` ou `ksp-wallet-api` n'est prévu actuellement. +- Les scenarios restent des crates spécialisées régies d'abord par une norme souple. ## Prévision souple des prereleases restantes -### `pre.002` — Inventaire initial des composants - -- créer `docs/architecture/004-COMPONENT_INVENTORY.md` ; -- fixer les responsabilités et statuts initiaux des composants ; -- enregistrer les workers/jobs/scénarios/apps actuellement prévus ; -- documenter les candidats `ksp-execution-policy-api` et `ksp-execution-lib` ; -- corriger la règle de charge série/release/session ; -- préparer explicitement les questions à résoudre dans `pre.003`. - ### `pre.003` — Graphe de dépendances et correction de l'inventaire -- construire le graphe autorisé/interdit ; -- décider si `ksp-execution-lib` dépend de `ksp-program-api`, `ksp-program-lib` ou reçoit des implémentations injectées ; -- définir la frontière program -> execution plan -> policy -> wallet/transport ; -- vérifier que transport ne dépend pas du store tout en gardant une conversion simple des modèles ; -- positionner materializer/store/notifications ; -- rechercher et supprimer les cycles ; -- corriger `004-COMPONENT_INVENTORY.md` si nécessaire. +Livré : + +- `docs/architecture/005-DEPENDENCY_GRAPH.md` ; +- graphe Program/Execution/Policy ; +- graphe Materializer/Store ; +- graphe Worker/Job ; +- conversion explicite des modèles aux frontières ; +- dépendances interdites et prévention des cycles ; +- correction de `004-COMPONENT_INVENTORY.md` ; +- suppression des décisions négatives présentées à tort comme tâches du roadmap. ### `pre.004` — Programmes, wire et exécution -- détailler `ksp-interface-lib`, `ksp-program-api`, `ksp-program-lib` ; -- détailler l'execution policy/orchestration si validées ; -- cadrer conformité wire, historique/deprecated et sécurité supérieure. +Objectifs prévus : + +- détailler `ksp-interface-lib` ; +- détailler `ksp-program-api` et `ksp-program-lib` ; +- définir précisément decoder API et executor API ; +- définir le contrat d'opération préparée ; +- définir `ksp-execution-policy-api` ; +- détailler le cycle de `ksp-execution-lib` : préparation, policy, simulation, signature, envoi, confirmation ; +- cadrer conformité wire, historique/deprecated et policy supérieure ; +- vérifier que la tranche reste dans le budget de complexité, sinon la scinder. ### `pre.005` — Données, store et acquisitions -- détailler materializer/store ; -- finaliser les modèles raw et notifications ; +- détailler `ksp-materializer-api` / `ksp-materializer-lib` ; +- détailler `ksp-store-api` / `ksp-store-lib` ; +- finaliser modèles raw/Core/generic/domain ; +- détailler notifications et mécanismes de diffusion possibles ; - détailler W1 et backfill ; -- cadrer les trois workers de processing futurs ; -- revisiter les niveaux durables/replay. +- cadrer les workers de processing ; +- revisiter niveaux durables, replay, provenance et idempotence. ### `pre.006` — Applications, workers, jobs, scenarios et pipelines spécialisés - formaliser les apps spécialisées ; - détailler `ksp-worker-control-lib` ; -- définir la norme des crates scénario et leurs apps demo ; +- définir la norme des crates scenario et leurs apps demo ; +- traiter les processus/IPC/managers ; +- cadrer l'orchestrateur futur ; - inventorier les pipelines spécialisés réellement nécessaires. ### `pre.007` — Plan des premières releases fonctionnelles - transformer les séries `0.1.x+` en premières releases concrètes ; -- dimensionner chaque release concrète plutôt que toute la série ; -- préparer le prompt de la première release `0.1.x` réellement choisie. +- dimensionner chaque release concrète ; +- choisir la première release `0.1.N` ; +- transformer le brouillon de prompt en prompt quasi-final de cette release concrète. ### `pre.008` — Clôture fondatrice - validations finales de cohérence ; - documentation/nettoyage/archivage ; +- synchronisation du changelog si applicable ; - finalisation du prompt de la première release fonctionnelle. -Le nombre de prereleases reste révisable si une tranche dépasse le budget de planification ou si une nouvelle frontière apparaît. +Le nombre de prereleases reste révisable si une tranche dépasse le budget de planification ou si une frontière supplémentaire doit être étudiée. diff --git a/docs/rules/RULES_DEPENDENCIES.md b/docs/rules/RULES_DEPENDENCIES.md index 1f74666..dfe5de1 100644 --- a/docs/rules/RULES_DEPENDENCIES.md +++ b/docs/rules/RULES_DEPENDENCIES.md @@ -1,36 +1,74 @@ - + # Règles des dépendances KSP ## Portée -Les règles `DEP-*` définissent quelles dépendances externes peuvent traverser les frontières KSP et quelles couches en sont propriétaires. +Les règles `DEP-*` définissent quelles dépendances externes et internes peuvent traverser les frontières KSP et quelles couches en sont propriétaires. -Elles complètent les règles Rust générales. Elles sont particulièrement strictes pour les crates liées à Solana et aux protocoles on-chain. +Elles complètent les règles Rust générales et le graphe de `docs/architecture/005-DEPENDENCY_GRAPH.md`. ## Firewall des exécutables -- **DEP-EXEC-001** — Les applications, demos et workers KSP ne dépendent directement d'aucune crate externe relative à Solana ou à un protocole Solana. Ils consomment exclusivement les bibliothèques KSP propriétaires de ces contrats. -- **DEP-EXEC-002** — Une application peut dépendre directement de bibliothèques générales non-Solana nécessaires à son interface ou à son runtime, par exemple UI, sérialisation, Base64 ou Base58, à condition que ces dépendances ne portent pas une opération métier/protocolaire appartenant à KSP. -- **DEP-EXEC-003** — Si un exécutable a besoin d'un type, d'une fonction ou d'un contrat Solana, la bibliothèque KSP propriétaire doit l'exposer ou fournir le wrapper/contrat approprié ; l'exécutable ne contourne pas cette frontière en ajoutant lui-même la crate Solana. +- **DEP-EXEC-001** — Les applications, demos, workers et jobs KSP ne dépendent directement d'aucune crate externe relative à Solana ou à un protocole Solana. Ils consomment exclusivement les composants KSP propriétaires de ces contrats. +- **DEP-EXEC-002** — Un exécutable peut dépendre directement de bibliothèques générales non-Solana nécessaires à son interface ou à son runtime, à condition qu'elles ne portent pas une opération métier/protocolaire appartenant à KSP. +- **DEP-EXEC-003** — Si un exécutable a besoin d'un type, d'une fonction ou d'un contrat Solana, le composant KSP propriétaire doit l'exposer ou fournir le wrapper/contrat approprié. + +## Direction des dépendances internes + +- **DEP-KSP-001** — Une crate `ksp--api` ne dépend jamais de l'implémentation officielle `ksp--lib`. +- **DEP-KSP-002** — Une bibliothèque basse de transformation/sémantique ne dépend pas d'un worker, job, application ou orchestrateur qui la consomme. +- **DEP-KSP-003** — Les conversions entre modèles de transport, processing et persistence sont réalisées par les composants de composition appropriés plutôt que par des dépendances croisées entre domaines. +- **DEP-KSP-004** — Aucun `ksp-data-api` global n'est introduit uniquement pour éviter des conversions explicites entre modèles appartenant à des responsabilités différentes. +- **DEP-KSP-005** — Une dépendance autorisée par le graphe n'est ajoutée au manifeste que lorsqu'un usage réel la justifie. + +## 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-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-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`. + +## Materializer / Store + +- **DEP-MAT-001** — `ksp-materializer-api` peut dépendre de `ksp-program-api` lorsque les contrats de matérialisation consomment des sorties canoniques de processing. +- **DEP-MAT-002** — `ksp-materializer-api` et `ksp-materializer-lib` ne dépendent pas de `ksp-store-api` ou `ksp-store-lib`. +- **DEP-STORE-001** — `ksp-store-api` ne dépend pas de Program, Materializer ou Transport. +- **DEP-STORE-002** — `ksp-store-lib` dépend de `ksp-store-api` et contient l'implémentation PostgreSQL de référence ; il ne dépend pas des implémentations Program/Materializer/Transport. +- **DEP-STORE-003** — Les workers/jobs spécialisés sont propriétaires des conversions entre modèles runtime et DTO persistants. + +## Transport + +- **DEP-TRANSPORT-001** — `ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api` ou `ksp-store-lib`. +- **DEP-TRANSPORT-002** — Les providers on-chain normalisent leurs réponses dans des modèles KSP homogènes par catégorie de données avant exposition aux consommateurs. +- **DEP-TRANSPORT-003** — Les modèles de transport ne réalisent pas de décodage métier/protocolaire et doivent rester facilement convertibles en DTO raw persistants. +- **DEP-TRANSPORT-004** — Aucun `ksp-onchain-transport-api` ou `ksp-offchain-transport-api` global n'est créé dans l'architecture actuelle. + +## Worker / Job lifecycle + +- **DEP-WORKER-001** — `ksp-worker-control-lib` dépend de `ksp-worker-api` et ne dépend pas de `ksp-job-api`. +- **DEP-JOB-001** — `ksp-job-api` ne dépend ni de `ksp-worker-api` ni de `ksp-worker-control-lib`. +- **DEP-JOB-002** — Un orchestrateur futur peut consommer séparément les APIs/contrôles workers et jobs sans introduire un lifecycle parent commun. ## Propriété des dépendances Solana -- **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir une bibliothèque KSP propriétaire précise. Elle n'est pas ajoutée dans plusieurs couches uniquement parce qu'elle est pratique à utiliser. +- **DEP-SOL-001** — Une dépendance externe relative à Solana doit avoir un composant KSP propriétaire précis. - **DEP-SOL-002** — Les bibliothèques KSP de haut niveau qui n'ont pas besoin d'un contrat externe bas niveau ne dépendent pas directement de ce contrat. - **DEP-SOL-003** — Les primitives Solana/Anza suffisamment fondamentales et stables peuvent être utilisées dans les bibliothèques KSP de bas niveau qui en sont propriétaires. - **DEP-SOL-004** — La liste initialement acceptée de primitives fondamentales comprend `solana-pubkey`, `solana-keypair`, `solana-signer`, `solana-hash` et `solana-nonce`. -- **DEP-SOL-005** — L'ajout d'une autre crate Solana/Anza est décidé à partir d'un besoin concret et de sa stabilité/API ; l'appartenance au dépôt Solana/Anza ne constitue pas à elle seule une autorisation automatique. -- **DEP-SOL-006** — Une bibliothèque KSP peut exposer ou réexporter une primitive externe fondamentale lorsque cette primitive fait intentionnellement partie du contrat KSP ; l'exécutable consommateur dépend alors de KSP, pas directement de la crate externe. +- **DEP-SOL-005** — L'ajout d'une autre crate Solana/Anza est décidé à partir d'un besoin concret et de sa stabilité/API. +- **DEP-SOL-006** — Une bibliothèque KSP peut exposer ou réexporter une primitive externe fondamentale lorsque cette primitive fait intentionnellement partie du contrat KSP. ## Crates de protocoles et interfaces wire - **DEP-PROTO-001** — Les crates d'interface/protocole externes telles que `mpl-token-metadata` ou `spl-elgamal-registry-interface` sont interdites par défaut comme dépendances runtime KSP. - **DEP-PROTO-002** — KSP préfère posséder ses représentations compatibles nécessaires : Program IDs, discriminants, layouts, enums, structures wire, règles de PDA, sérialisation/désérialisation et autres contrats effectivement requis. - **DEP-PROTO-003** — Une réimplémentation KSP vise le contrat nécessaire et ne consiste pas à copier mécaniquement l'architecture ou l'intégralité d'une crate externe. -- **DEP-PROTO-004** — La méthode de vérification de compatibilité wire, l'usage éventuel de dépendances externes uniquement en tests de conformité et les contraintes de licence/source de vérité restent à définir avant la première implémentation de protocole concernée. -- **DEP-PROTO-005** — Une dépendance protocolaire externe exceptionnellement nécessaire doit être explicitement justifiée, confinée à la bibliothèque propriétaire la plus basse possible et documentée avec sa version, sa raison et sa condition de suppression ou réévaluation. +- **DEP-PROTO-004** — La méthode de vérification de compatibilité wire et l'usage éventuel de dépendances externes uniquement en tests de conformité doivent être définis avant la première implémentation concernée. +- **DEP-PROTO-005** — Une dépendance protocolaire externe exceptionnellement nécessaire doit être explicitement justifiée et confinée au composant propriétaire le plus bas possible. ## Versions diff --git a/docs/rules/RULES_KSP.md b/docs/rules/RULES_KSP.md index 121a122..9edf0a1 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,9 @@ - **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** — La direction retenue est une API de policy d'exécution séparée, candidate `ksp-execution-policy-api`, afin que plusieurs contextes puissent fournir des politiques différentes sans modifier `ksp-program-lib`. +- **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 un candidat fort d'orchestration spécialisée entre programme, policy, wallet et transport. Son graphe exact est reporté à l'étude des dépendances. +- **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`. ## Transports @@ -71,11 +71,18 @@ - **KSP-JOB-007** — Aucune `ksp-job-control-lib` commune n'est prévue actuellement ; elle ne sera créée que si une duplication concrète entre plusieurs jobs le justifie. - **KSP-JOB-008** — Le contrôle/gouvernance des jobs reste séparé du contrôle des workers. +## Matérialisation et persistence + +- **KSP-MAT-001** — `ksp-materializer-api` peut dépendre de `ksp-program-api` ; `ksp-materializer-lib` dépend de son API mais ne dépend pas du store. +- **KSP-MAT-002** — `ksp-materializer-api` / `ksp-materializer-lib` ne réalisent pas eux-mêmes la persistance ; les workers/jobs/pipelines spécialisés composent matérialisation et store. +- **KSP-STORE-001** — `ksp-store-api` reste indépendant des APIs Program/Materializer/Transport et possède les contrats persistants. +- **KSP-STORE-002** — Les conversions entre modèles runtime et DTO persistants sont explicites aux frontières de composition ; aucun `ksp-data-api` global n'est introduit actuellement. + ## Notifications de données - **KSP-DATA-001** — Une notification de donnée décrit la donnée disponible et non le worker/job qui l'a produite. - **KSP-DATA-002** — Le même type de donnée utilise le même contrat de notification quelle que soit son origine : worker, job, import ou autre source. -- **KSP-DATA-003** — `ksp-store-api` est le propriétaire candidat des références/notifications canoniques de données persistées lorsque ces contrats appartiennent naturellement à la frontière store. +- **KSP-DATA-003** — `ksp-store-api` est le propriétaire retenu des références/notifications canoniques lorsqu'elles signifient qu'une donnée persistée est disponible. - **KSP-DATA-004** — Le contrat de notification est séparé de son mécanisme de transport concret. ## Pipelines et scénarios diff --git a/prompts/001-V0_1_X_START_PROMPT.md b/prompts/001-V0_1_X_START_PROMPT.md index 432d509..f729c1d 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` à `004`, 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` à `005`, 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. +- 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. - Les règles fines de naming/arborescence/API publique seront définies à partir des premières APIs réelles. ## 7. Hors périmètre de la série N1