316 lines
12 KiB
Markdown
316 lines
12 KiB
Markdown
<!-- file: docs/IDEAS.md -->
|
||
<!-- version: 14 -->
|
||
|
||
# Idées à explorer
|
||
|
||
Ce document conserve les idées, pistes, questions et alternatives qui méritent d'être étudiées sans constituer encore un engagement de développement ou une décision architecturale.
|
||
|
||
## Statuts
|
||
|
||
- `À explorer`
|
||
- `En exploration`
|
||
- `Retenue`
|
||
- `Rejetée`
|
||
- `Transférée au roadmap`
|
||
- `Transférée vers une décision/règle`
|
||
|
||
## APIs et extensibilité
|
||
|
||
### Nomenclature `*-api`
|
||
|
||
**Status :** Retenue
|
||
|
||
Les crates de contrats publics extensibles utilisent `ksp-<domain>-api`, sans suffixe `-lib`.
|
||
|
||
Premiers couples retenus : program, materializer et store. Les APIs worker/job sont des lifecycle APIs distinctes.
|
||
|
||
### Execution policy API
|
||
|
||
**Status :** Transférée vers une décision/règle
|
||
|
||
`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.
|
||
|
||
L'UI sélectionne/injecte une implémentation réutilisable ; elle ne doit pas devenir propriétaire d'une politique complexe.
|
||
|
||
### Execution orchestration
|
||
|
||
**Status :** Transférée vers une décision/règle
|
||
|
||
`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`.
|
||
|
||
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
|
||
|
||
**Status :** Retenue
|
||
|
||
Ne pas créer `ksp-scenario-api` pour l'instant.
|
||
|
||
Définir d'abord une norme souple de structure, métadonnées, exécution et résultat des crates `ksp-scenario-<domain>-lib`, sans imposer un trait Rust qui limiterait des scénarios hétérogènes.
|
||
|
||
Réévaluer seulement si les premières implémentations révèlent un vrai contrat commun.
|
||
|
||
### Type d'erreur KSP unique
|
||
|
||
**Status :** En exploration
|
||
|
||
La direction retenue est un seul type public `ksp_core_lib::Error` consommable par le workspace sans obliger `ksp-core-lib` à connaître chaque domaine supérieur.
|
||
|
||
### Nommage des items publics
|
||
|
||
**Status :** À explorer
|
||
|
||
Définir avec les premières APIs réelles les conventions de nommage des traits, structs, enums, aliases, constantes et autres items exportés publiquement.
|
||
|
||
### Arborescence et réexports
|
||
|
||
**Status :** À explorer
|
||
|
||
Définir avec les premières crates fonctionnelles les conventions d'arborescence, façades `lib.rs`, modules API et réexports publics.
|
||
|
||
## Transport
|
||
|
||
### Modèles homogènes on-chain
|
||
|
||
**Status :** Retenue
|
||
|
||
`ksp-onchain-transport-lib` ne dépend pas de `ksp-store-api`, mais ses différents providers doivent exposer des modèles homogènes par catégorie de données afin que `ksp-worker-raw-retriever` puisse les convertir simplement vers les modèles raw persistants du store.
|
||
|
||
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
|
||
|
||
`ksp-offchain-transport-lib` regroupe metadata, prix, quotes, routage et autres accès externes afin d'éviter une explosion de crates. Il n'est pas nécessaire de leur inventer une API métier commune.
|
||
|
||
## Workers et jobs
|
||
|
||
### Workers de processing
|
||
|
||
**Status :** Retenue
|
||
|
||
Après `ksp-worker-raw-retriever`, les responsabilités de processing actuellement prévues sont séparées :
|
||
|
||
- `ksp-worker-core-processor` ;
|
||
- `ksp-worker-generic-materializer` ;
|
||
- `ksp-worker-domain-projector` (nom provisoire).
|
||
|
||
### Worker control
|
||
|
||
**Status :** Retenue comme direction
|
||
|
||
`ksp-worker-control-lib` doit être une implémentation réutilisable de gouvernance consommable par des applications desktop manager, puis par la future application globale et, si un besoin réel le justifie, par un éventuel orchestrateur commun.
|
||
|
||
### Job control
|
||
|
||
**Status :** Rejetée pour l'instant
|
||
|
||
Ne pas créer `ksp-job-control-lib` sans duplication concrète entre plusieurs jobs. `ksp-job-api` suffit comme lifecycle API commune tant que chaque job peut être gouverné directement via son implémentation.
|
||
|
||
## Wallet : applications futures
|
||
|
||
### Wallet Android
|
||
|
||
**Status :** À explorer — futur lointain
|
||
|
||
Une application Android native utilisant `ksp-wallet-lib` est envisagée. Nom exact à définir plus tard, candidat : `ksp-app-wallet-android`.
|
||
|
||
### Extensions navigateur
|
||
|
||
**Status :** À explorer — futur lointain
|
||
|
||
Prévoir potentiellement des extensions Firefox et Chrome consommant les capacités KSP appropriées. Noms candidats non normatifs :
|
||
|
||
```text
|
||
ksp-app-wallet-firefox-extension
|
||
ksp-app-wallet-chrome-extension
|
||
```
|
||
|
||
Le modèle de sécurité, la frontière Rust/WebAssembly/native et le stockage des secrets devront être étudiés avant toute décision.
|
||
|
||
### Wallet web
|
||
|
||
**Status :** À explorer — futur lointain
|
||
|
||
Un wallet web/online utilisant les contrats KSP est envisagé. La gestion des secrets et le modèle de confiance devront être traités comme une question architecturale majeure avant développement.
|
||
|
||
## Pipelines
|
||
|
||
### Pas de pipeline monolithique
|
||
|
||
**Status :** Retenue
|
||
|
||
Ne pas créer de `ksp-pipeline-lib`. Les pipelines sont introduits séparément à la demande avec un périmètre concret.
|
||
|
||
## Trading
|
||
|
||
### Trading Intelligence avant application de trading
|
||
|
||
**Status :** Retenue
|
||
|
||
Construire d'abord statistiques, features, signaux, risque, backtests, détection de patterns/anomalies et intégrations ML telles que XGBoost. La couche/application de trading opérationnelle est construite ensuite.
|
||
|
||
## Program API — questions d'implémentation
|
||
|
||
### Payload décodé ouvert et persistable
|
||
|
||
**Status :** À explorer lors de la première implémentation
|
||
|
||
`ksp-program-api` ne doit utiliser ni enum central fermé de Program IDs ni `Any` comme seule représentation.
|
||
|
||
À décider à partir des besoins réels :
|
||
|
||
- value tree typé KSP ;
|
||
- schema/version + payload binaire ;
|
||
- structure sérialisable ouverte ;
|
||
- autre contrat garantissant identification, persistence et extensibilité.
|
||
|
||
### Conflits de registry
|
||
|
||
**Status :** À explorer
|
||
|
||
Définir la politique lorsqu'un registry reçoit plusieurs implémentations capables de traiter le même Program ID/surface/version :
|
||
|
||
- priorité explicite ;
|
||
- refus du conflit ;
|
||
- sélection par version/capability ;
|
||
- autre mécanisme documenté.
|
||
|
||
### Convention interne `dec` / `exec_prep`
|
||
|
||
**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.
|
||
|
||
## Data / Store — questions d'implémentation
|
||
|
||
### Schémas SQL D1/D2/D3/D4
|
||
|
||
**Status :** À explorer avec la première release Store
|
||
|
||
La structure durable D1–D4 est retenue, mais les noms de tables, colonnes, contraintes, index et repositories doivent être conçus avec les premiers workloads réels.
|
||
|
||
### Format générique D3
|
||
|
||
**Status :** À explorer
|
||
|
||
Le journal D3 doit accepter les outputs de materializers officiels ou externes sans nécessiter une nouvelle table par materializer.
|
||
|
||
À définir : identité/type/domain, payload, hash, provenance, version processor, état current/superseded/failed/replay et stratégie de sérialisation.
|
||
|
||
### Backlog et checkpoints
|
||
|
||
**Status :** Transférée vers une décision/règle
|
||
|
||
Les processing outcomes par processor/version/capability constituent la vérité du backlog. Les cursors sont des optimisations et les jobs historiques conservent en plus leurs checkpoints de source.
|
||
|
||
### Jobs de replay
|
||
|
||
**Status :** Transférée vers une décision/règle
|
||
|
||
Trois jobs distincts sont retenus : `ksp-job-replay-core`, `ksp-job-replay-generic-materialization` et `ksp-job-replay-domain-projection`. Ils réutilisent les pipelines spécialisés correspondants.
|
||
|
||
### Notification backend de référence
|
||
|
||
**Status :** Transférée vers une décision/règle
|
||
|
||
PostgreSQL LISTEN/NOTIFY est retenu comme mécanisme initial de référence de wake-up, combiné à un periodic polling du backlog. Le Store reste la source de vérité.
|
||
|
||
## Workers / jobs — questions d'implémentation restantes
|
||
|
||
### Claim/lease PostgreSQL
|
||
|
||
**Status :** À explorer avec la première implémentation Store/worker
|
||
|
||
Définir le schéma SQL, la durée/renouvellement de lease et la technique PostgreSQL exacte permettant plusieurs instances concurrentes sans bloquer définitivement un input après crash.
|
||
|
||
### Processing outcomes
|
||
|
||
**Status :** À explorer avec D2/D3/D4 réels
|
||
|
||
Fixer les noms/types exacts et distinguer Produced, NoOutput, NotApplicable, Unsupported et failure déterministe sans transformer des situations normales en erreurs.
|
||
|
||
### Contexte stateful des projectors
|
||
|
||
**Status :** À explorer avec la première projection nécessitant un état existant
|
||
|
||
Le Store est interrogé par le pipeline/worker puis le contexte est injecté au `DomainProjector`. Définir comment le projector décrit les données de contexte nécessaires sans dépendre du backend.
|
||
|
||
### Job pause/resume
|
||
|
||
**Status :** À explorer avec `ksp-job-api`
|
||
|
||
Checkpoint/restart est nécessaire pour backfill/replay. Déterminer si pause/resume doit être une capability générique ou rester spécifique aux jobs qui la supportent.
|
||
|
||
### Télémétrie opérationnelle
|
||
|
||
**Status :** À explorer
|
||
|
||
Backlog count, oldest pending age, processing rate et failure rate doivent être observables. Décider plus tard si health/status + logging suffisent ou si une API/metrics exporter dédiée devient nécessaire.
|
||
|
||
## Applications et orchestration futures
|
||
|
||
### Application globale de contrôle/exploitation
|
||
|
||
**Status :** Future certaine, non planifiée actuellement
|
||
|
||
Une application globale de contrôle/exploitation est attendue à terme.
|
||
|
||
Elle ne doit pas être construite avant les applications spécialisées et demos nécessaires pour valider séparément config, wallet, Store, Program/execution, scenarios, workers/jobs et futurs domaines.
|
||
|
||
Son nom, son périmètre et sa release ne sont pas fixés.
|
||
|
||
### Orchestrateur global
|
||
|
||
**Status :** À réévaluer plus tard
|
||
|
||
Un orchestrateur pourra devenir utile pour coordonner plusieurs services, policies de restart/shutdown et déclenchements de jobs.
|
||
|
||
Aucune crate `ksp-orchestrator-lib` n'est retenue actuellement.
|
||
|
||
### IPC worker control
|
||
|
||
**Status :** À explorer au premier manager/service réel
|
||
|
||
Les workers sont des services autonomes. Une app manager devra donc disposer d'un transport de control.
|
||
|
||
Ne pas créer de `ksp-ipc-api` générique avant de connaître les contraintes réelles du premier manager : plateforme, framing, discovery, authentication locale et lifecycle.
|
||
|
||
## Séquencement des releases futures
|
||
|
||
### Numérotation fine après `0.1.x`
|
||
|
||
**Status :** À décider à l'approche de chaque série
|
||
|
||
`0.1.1` et `0.1.2` sont fixées ; `0.1.3` / `0.1.4` constituent la séquence par défaut sous réserve d'une éventuelle scission de Config.
|
||
|
||
Pour `0.2.x+`, ne pas attribuer prématurément un numéro précis à chaque composant. L'ordre candidat est documenté dans `docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md` et sera converti en releases concrètes lorsque les dépendances et premiers cas d'usage de la série seront connus.
|