v0.0.3-pre.010
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# file: Cargo.toml
|
||||
# version: 15
|
||||
# version: 16
|
||||
|
||||
[workspace]
|
||||
resolver = "3"
|
||||
members = ["crates/ksp-core-lib"]
|
||||
|
||||
[workspace.package]
|
||||
version = "0.0.3-pre.9"
|
||||
version = "0.0.3-pre.10"
|
||||
edition = "2024"
|
||||
license = "MIT"
|
||||
repository = "https://git.sasedev.com/Sasedev/khadhroony-solana-project"
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: ROADMAP.md -->
|
||||
<!-- version: 10 -->
|
||||
<!-- version: 11 -->
|
||||
|
||||
# Roadmap KSP
|
||||
|
||||
@@ -21,7 +21,7 @@ Les décisions architecturales négatives ou de prudence n'apparaissent pas comm
|
||||
- [X] `0.0.2` — Installer le squelette minimal et les règles initiales.
|
||||
- [/] `0.0.3` — Définir domaines, composants, dépendances, contrats, workers/jobs/scénarios/apps et plan global.
|
||||
- [X] Sélectionner `0.1.1` comme première release fonctionnelle et produire son prompt quasi-final.
|
||||
- [ ] Clôturer la fondation avec documentation, validations et prompt final.
|
||||
- [/] Clôturer la fondation avec documentation, validations et prompt final ; publication stable `0.0.3` en attente des validations Cargo locales.
|
||||
|
||||
## 0.1.x — Fondations N1
|
||||
|
||||
@@ -67,7 +67,7 @@ Les contrats publics supplémentaires ne sont introduits que lorsqu'une release
|
||||
|
||||
## 0.4.x — Baseline Solana, SPL et metadata
|
||||
|
||||
- [ ] Ajouter progressivement les decoders/executors Core/SPL nécessaires.
|
||||
- [ ] Ajouter progressivement les decoders et `ProgramExecutionPreparer` Core/SPL nécessaires.
|
||||
- [ ] Ajouter Token, Token-2022, ATA et metadata utiles.
|
||||
- [ ] Introduire `ksp-offchain-transport-lib` au plus tard au premier besoin externe.
|
||||
- [ ] Ajouter materializers et jobs ponctuels nécessaires.
|
||||
@@ -107,7 +107,7 @@ Les contrats publics supplémentaires ne sont introduits que lorsqu'une release
|
||||
|
||||
- [ ] Construire les couches puis l'application de trading monoposte au-dessus de Trading Intelligence.
|
||||
- [ ] Étendre l'automatisation de trading.
|
||||
- [ ] Étendre continuellement Program IDs, decoders/executors/materializers.
|
||||
- [ ] Étendre continuellement Program IDs, decoders, execution preparers et materializers.
|
||||
- [ ] Construire progressivement l'explorer Solana.
|
||||
- [ ] Construire progressivement l'explorer/analyse DEX.
|
||||
- [ ] Étudier plus tard d'autres applications utilisant `ksp-wallet-lib`, notamment mobile, extensions navigateur et web.
|
||||
|
||||
165
deltas/0.0.3/pre.010.md
Normal file
165
deltas/0.0.3/pre.010.md
Normal file
@@ -0,0 +1,165 @@
|
||||
<!-- file: deltas/0.0.3/pre.010.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta 0.0.3-pre.010
|
||||
|
||||
## Base requise
|
||||
|
||||
`v0.0.3-pre.009`.
|
||||
|
||||
## Objectif
|
||||
|
||||
Clôturer l'architecture fondatrice `0.0.3`, effectuer l'audit de cohérence final, finaliser le prompt `0.1.1` et préparer la publication stable sans déclarer de validations Rust qui n'ont pas pu être exécutées.
|
||||
|
||||
## Version Cargo
|
||||
|
||||
`workspace.package.version` passe de :
|
||||
|
||||
```text
|
||||
0.0.3-pre.9
|
||||
```
|
||||
|
||||
à :
|
||||
|
||||
```text
|
||||
0.0.3-pre.10
|
||||
```
|
||||
|
||||
Le header de `Cargo.toml` passe de version 15 à 16.
|
||||
|
||||
## Fichiers ajoutés
|
||||
|
||||
- `deltas/0.0.3/pre.010.md`
|
||||
|
||||
## Fichiers modifiés
|
||||
|
||||
- `Cargo.toml`
|
||||
- `ROADMAP.md`
|
||||
- `docs/000-README.md`
|
||||
- `docs/IDEAS.md`
|
||||
- `docs/architecture/002-LAYERS_AND_DEPENDENCIES.md`
|
||||
- `docs/architecture/004-COMPONENT_INVENTORY.md`
|
||||
- `docs/architecture/005-DEPENDENCY_GRAPH.md`
|
||||
- `docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`
|
||||
- `docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`
|
||||
- `docs/plans/000-README.md`
|
||||
- `docs/plans/001-V0_0_3_PLAN.md`
|
||||
- `docs/rules/RULES_KSP.md`
|
||||
- `docs/rules/VERSION_WORKFLOW.md`
|
||||
- `prompts/000-README.md`
|
||||
- `prompts/001-V0_1_1_START_PROMPT.md`
|
||||
|
||||
## Fichiers supprimés
|
||||
|
||||
Aucun nouveau fichier supprimé dans ce delta.
|
||||
|
||||
Les anciens fichiers de prompt supprimés par les deltas précédents restent supprimés :
|
||||
|
||||
```text
|
||||
prompts/001-PROMPT_STRUCTURE.md
|
||||
prompts/002-V0_1_X_START_PROMPT.md
|
||||
prompts/001-V0_1_X_START_PROMPT.md
|
||||
```
|
||||
|
||||
## Audit de cohérence
|
||||
|
||||
La base d'audit a été reconstruite à partir du squelette `0.0.2` et des archives/deltas `0.0.3-pre.001` à `pre.009`, en appliquant explicitement les suppressions historiques.
|
||||
|
||||
Corrections réalisées :
|
||||
|
||||
- index `prompts/000-README.md` encore pointé vers l'ancien prompt générique ;
|
||||
- `docs/000-README.md` ne reflétait plus l'arbre documentaire actuel ;
|
||||
- `docs/plans/000-README.md` n'indexait pas le plan de séquence fonctionnelle ;
|
||||
- deux identifiants normatifs `KSP-MAT-001` / `KSP-MAT-002` étaient dupliqués ;
|
||||
- plusieurs références de documents d'architecture pointaient encore vers des prereleases déjà terminées ;
|
||||
- plusieurs termes `executor` historiques restaient employés alors que `ProgramExecutionPreparer` est la frontière retenue ;
|
||||
- certaines listes de questions indiquaient encore comme ouvertes des décisions déjà clôturées par `pre.004` à `pre.008`.
|
||||
|
||||
## Décisions confirmées
|
||||
|
||||
Aucune nouvelle architecture majeure n'est introduite.
|
||||
|
||||
La clôture confirme notamment :
|
||||
|
||||
- `0.1.1` = `ksp-core-lib` ;
|
||||
- `0.1.2` = `ksp-logging-lib` ;
|
||||
- `0.1.3` = Config par défaut, scindable si nécessaire ;
|
||||
- apps spécialisées/demos avant application globale ;
|
||||
- workers autonomes en package lib + bin mince ;
|
||||
- `ProgramExecutionPreparer` séparé de l'exécution transactionnelle ;
|
||||
- D1/D2/D3/D4 ;
|
||||
- pipelines spécialisés ;
|
||||
- Store comme source de vérité des backlogs ;
|
||||
- notifications comme wake-up ;
|
||||
- scenarios dans leurs crates `ksp-scenario-<domain>-lib`.
|
||||
|
||||
## Prompt `0.1.1`
|
||||
|
||||
`prompts/001-V0_1_1_START_PROMPT.md` passe de `Quasi-final` à `Final`.
|
||||
|
||||
Il exige comme base la release stable/taguée :
|
||||
|
||||
```text
|
||||
v0.0.3
|
||||
```
|
||||
|
||||
## Validations exécutées
|
||||
|
||||
### Reconstruction
|
||||
|
||||
- reconstruction de la base complète depuis les archives disponibles ;
|
||||
- application explicite des suppressions historiques de prompts et probes de test transitoires.
|
||||
|
||||
### Audit documentaire automatique
|
||||
|
||||
- headers `file:` / `version:` vérifiés ;
|
||||
- liens Markdown locaux vérifiés ;
|
||||
- doublons d'identifiants normatifs vérifiés ;
|
||||
- références vers les anciens prompts vérifiées ;
|
||||
- `Cargo.toml` parsé ;
|
||||
- version `0.0.3-pre.10` vérifiée dans le patch final.
|
||||
|
||||
## Validations tentées mais non exécutées
|
||||
|
||||
Les commandes suivantes ont été tentées dans l'environnement de génération :
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
Résultat de l'environnement :
|
||||
|
||||
```text
|
||||
cargo: command not found
|
||||
```
|
||||
|
||||
Elles ne sont donc **pas déclarées réussies**.
|
||||
|
||||
## Condition de publication stable
|
||||
|
||||
Avant de produire/appliquer `0.0.3-rel.001`, exécuter sur le dépôt réel :
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
Si elles réussissent, `rel.001` doit rester une publication bornée :
|
||||
|
||||
- `workspace.package.version = "0.0.3"` ;
|
||||
- roadmap `0.0.3` / clôture fondatrice marqués `[X]` ;
|
||||
- delta `deltas/0.0.3/rel.001.md` ;
|
||||
- commit de release puis tag `v0.0.3`.
|
||||
|
||||
Toute erreur détectée ouvre d'abord un correctif `pre.010-fix.NNN` ou une correction appropriée avant `rel.001`.
|
||||
|
||||
## Questions ouvertes
|
||||
|
||||
Les questions d'implémentation futures restent dans `docs/IDEAS.md` et les documents d'architecture.
|
||||
|
||||
Aucune question fondatrice bloquante connue ne reste ouverte hors validation Cargo locale.
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/000-README.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Documentation KSP
|
||||
|
||||
@@ -23,10 +23,18 @@ docs/
|
||||
│ ├── 000-README.md
|
||||
│ ├── 001-PROJECT_OBJECTIVES.md
|
||||
│ ├── 002-LAYERS_AND_DEPENDENCIES.md
|
||||
│ └── 003-COMPONENT_CONTRACTS.md
|
||||
│ ├── 003-COMPONENT_CONTRACTS.md
|
||||
│ ├── 004-COMPONENT_INVENTORY.md
|
||||
│ ├── 005-DEPENDENCY_GRAPH.md
|
||||
│ ├── 006-WIRE_AND_PROGRAM.md
|
||||
│ ├── 007-EXECUTION_AND_POLICY.md
|
||||
│ ├── 008-DATA_MATERIALIZATION_AND_STORE.md
|
||||
│ ├── 009-ACQUISITION_WORKERS_AND_JOBS.md
|
||||
│ └── 010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md
|
||||
├── plans/
|
||||
│ ├── 000-README.md
|
||||
│ └── 001-V0_0_3_PLAN.md
|
||||
│ ├── 001-V0_0_3_PLAN.md
|
||||
│ └── 002-FUNCTIONAL_RELEASE_SEQUENCE.md
|
||||
└── rules/
|
||||
├── FILE_CONTRACTS.md
|
||||
├── PROMPT_STRUCTURE.md
|
||||
@@ -35,6 +43,7 @@ docs/
|
||||
├── RULES_GENERAL.md
|
||||
├── RULES_KSP.md
|
||||
├── RULES_RUST.md
|
||||
├── SCENARIO_CONVENTION.md
|
||||
└── VERSION_WORKFLOW.md
|
||||
```
|
||||
|
||||
@@ -42,7 +51,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é
|
||||
|
||||
## Documents actifs de planification
|
||||
|
||||
Le plan actif de la phase fondatrice est [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md).
|
||||
La clôture de la phase fondatrice est suivie dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md).
|
||||
|
||||
`IDEAS.md` conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/IDEAS.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Idées à explorer
|
||||
|
||||
@@ -110,7 +110,7 @@ Après `ksp-worker-raw-retriever`, les responsabilités de processing actuelleme
|
||||
|
||||
**Status :** Retenue comme direction
|
||||
|
||||
`ksp-worker-control-lib` doit être une implémentation réutilisable de gouvernance consommable par des applications desktop manager, une future application globale et l'orchestrateur.
|
||||
`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
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
|
||||
<!-- version: 4 -->
|
||||
<!-- version: 5 -->
|
||||
|
||||
# Couches et dépendances KSP
|
||||
|
||||
@@ -32,7 +32,7 @@ Une bibliothèque N1 ne doit pas dépendre d'une fonctionnalité métier située
|
||||
|
||||
N2 regroupe les capacités réutilisables opérant sur Solana au-dessus des fondations.
|
||||
|
||||
Le nom `ksp-program-lib` est retenu pour la future bibliothèque propriétaire du traitement des programmes : décodage et opérations techniquement constructibles/exécutables. Elle doit s'appuyer sur `ksp-interface-lib` plutôt que faire porter les contrats wire aux applications.
|
||||
Le nom `ksp-program-lib` est retenu pour la bibliothèque propriétaire du traitement des programmes : décodage et préparation technique d'opérations via `ProgramExecutionPreparer`. Elle doit s'appuyer sur `ksp-interface-lib` plutôt que faire porter les contrats wire aux applications.
|
||||
|
||||
Les autres responsabilités N2 candidates comprennent notamment :
|
||||
|
||||
@@ -72,11 +72,11 @@ W1 :
|
||||
- ne décide pas de l'utilisation métier des données collectées ;
|
||||
- doit pouvoir faire évoluer à chaud ce qu'il écoute, rapatrie ou stocke selon les mécanismes de configuration/commande qui seront définis.
|
||||
|
||||
Les consommateurs des notifications W1 décident eux-mêmes s'ils doivent décoder, matérialiser ou effectuer un autre traitement.
|
||||
Les notifications W1 servent de wake-up. Les workers/jobs downstream reconstruisent leur backlog depuis le Store et appliquent les pipelines spécialisés correspondant aux frontières D1 -> D2 -> D3 -> D4.
|
||||
|
||||
### Workers de processing futurs
|
||||
|
||||
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 D1 Raw -> D2 Core -> D3 journal de matérialisation générique -> D4 projections de domaine. Leur détail sera repris dans la tranche consacrée aux workers/data.
|
||||
Le processing continu n'est plus modélisé comme un unique W2. Il sépare `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector` afin de respecter les frontières durables D1 Raw -> D2 Core -> D3 journal de matérialisation générique -> D4 projections de domaine. Le lifecycle, backlog, claim/lease et replay sont détaillés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
|
||||
|
||||
## N4 — Exécutables
|
||||
|
||||
@@ -141,7 +141,7 @@ Les workers sont différents des interfaces utilisateur. Ils peuvent contenir l'
|
||||
|
||||
Un worker doit néanmoins consommer les bibliothèques KSP propriétaires des contrats Solana et ne doit pas dépendre directement de crates Solana/protocoles externes.
|
||||
|
||||
Les premiers managers de workers peuvent être spécialisés et séparés. Un orchestrateur global sera introduit ultérieurement lorsque plusieurs workers/managers justifieront réellement cette abstraction.
|
||||
Les premiers managers de workers sont spécialisés et séparés. Une application globale est un produit futur, tandis qu'un orchestrateur commun reste une abstraction à réévaluer seulement lorsqu'un besoin opérationnel concret le justifie.
|
||||
|
||||
## Firewall des dépendances externes
|
||||
|
||||
@@ -182,7 +182,7 @@ Les contrats minimaux entre couches doivent être définis suffisamment tôt pou
|
||||
Ce principe s'applique notamment aux futurs :
|
||||
|
||||
- decoders ;
|
||||
- executors/constructeurs d'opérations ;
|
||||
- `ProgramExecutionPreparer` / constructeurs d'opérations ;
|
||||
- materializers ;
|
||||
- store/repositories ;
|
||||
- transports ;
|
||||
@@ -194,9 +194,9 @@ Il ne signifie pas qu'il faut implémenter prématurément toutes les fonctionna
|
||||
|
||||
## Questions encore ouvertes
|
||||
|
||||
- représentation interne exacte du type d'erreur commun KSP ;
|
||||
- découpage interne précis de `ksp-program-lib` ;
|
||||
- politique de sécurité/exécution située au-dessus de `ksp-program-lib` ;
|
||||
- position précise du pipeline et du futur orchestrateur ;
|
||||
- représentation interne exacte du type d'erreur commun KSP, à traiter dès `0.1.1-pre.001` ;
|
||||
- types publics précis de `ksp-program-api` et format ouvert/persistable des résultats décodés ;
|
||||
- méthode de conformité wire contre les projets externes ;
|
||||
- graphe de dépendances précis crate par crate.
|
||||
- mécanisme IPC du premier manager de worker autonome ;
|
||||
- besoins de contexte des futurs `DomainProjector` stateful ;
|
||||
- nécessité réelle d'un orchestrateur commun lorsque plusieurs services/managers existeront.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
|
||||
<!-- version: 8 -->
|
||||
<!-- version: 10 -->
|
||||
|
||||
# Inventaire initial des composants KSP
|
||||
|
||||
@@ -133,7 +133,7 @@ Ces modèles :
|
||||
- ne réalisent aucun décodage métier/protocolaire ;
|
||||
- doivent être facilement et explicitement convertibles par `ksp-worker-raw-retriever` vers les modèles raw persistants de `ksp-store-api`.
|
||||
|
||||
Le détail de cette frontière de conversion est reporté à `pre.003/pre.005`.
|
||||
Les principes de cette frontière sont désormais fixés : transport et Store restent indépendants, et la conversion explicite transport -> D1 appartient au pipeline/composant de composition. Les DTO exacts seront définis avec les premières implémentations Transport/Store.
|
||||
|
||||
## Transport off-chain
|
||||
|
||||
@@ -167,7 +167,7 @@ Elle doit pouvoir être consommée par :
|
||||
|
||||
- une application desktop manager spécialisée ;
|
||||
- une future application globale ;
|
||||
- un futur orchestrateur ;
|
||||
- un éventuel orchestrateur commun si un besoin opérationnel concret le justifie ;
|
||||
- des tools/tests lorsque pertinent.
|
||||
|
||||
Les applications restent des interfaces et ne réimplémentent pas elles-mêmes registre, dispatch start/stop, agrégation d'état ou reconfiguration générique.
|
||||
@@ -334,11 +334,11 @@ Le graphe confirme les principes suivants :
|
||||
- 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
|
||||
## Questions restantes après la fondation
|
||||
|
||||
- `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 ;
|
||||
- types Rust exacts des contrats ouverts de `ksp-program-api` ;
|
||||
- DTO exacts des modèles transport et D1/D2/D3/D4 avec les premières implémentations concernées ;
|
||||
- schémas SQL, indexes, claims/leases et pagination du Store PostgreSQL ;
|
||||
- première implémentation manager/service : mécanisme IPC et proxy distant Worker ;
|
||||
- futur : orchestrateur/application globale seulement lorsqu'un besoin opérationnel concret le justifie.
|
||||
- contexte requis par les projectors stateful ;
|
||||
- futur : orchestrateur commun seulement si un besoin opérationnel concret le justifie ; l'application globale reste un produit futur après validation des apps spécialisées.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
|
||||
<!-- version: 6 -->
|
||||
<!-- version: 7 -->
|
||||
|
||||
# Graphe de dépendances KSP
|
||||
|
||||
@@ -144,14 +144,17 @@ ksp-program-lib
|
||||
|
||||
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 :
|
||||
Le contrat de préparation retenu est centré sur :
|
||||
|
||||
```text
|
||||
PreparedProgramOperation
|
||||
ProgramExecutionPlan
|
||||
ProgramExecutionRequest
|
||||
↓
|
||||
ProgramExecutionPreparer
|
||||
↓
|
||||
PreparedProgramExecution
|
||||
```
|
||||
|
||||
Le choix du nom/type final n'est pas décidé ici.
|
||||
Les champs Rust exacts restent à définir avec la première implémentation, sans rouvrir la séparation préparation/exécution.
|
||||
|
||||
## Interdictions Program
|
||||
|
||||
@@ -456,7 +459,7 @@ notify
|
||||
|
||||
Le payload privilégie une référence durable compacte.
|
||||
|
||||
Le mécanisme concret peut être channel, PostgreSQL LISTEN/NOTIFY, IPC ou broker. Le choix détaillé est reporté à `pre.007`.
|
||||
Le contrat reste indépendant du mécanisme. PostgreSQL `LISTEN/NOTIFY` est retenu comme mécanisme initial de référence de wake-up, combiné à un polling périodique du backlog.
|
||||
|
||||
---
|
||||
|
||||
@@ -849,29 +852,13 @@ Les conversions entre Program/Materializer/Store ne sont pas résolues par des d
|
||||
|
||||
---
|
||||
|
||||
# Questions reportées
|
||||
# Questions restantes
|
||||
|
||||
`pre.004` doit détailler :
|
||||
Les grandes frontières de dépendances sont désormais fixées. Restent à résoudre avec les premières implémentations :
|
||||
|
||||
- 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.
|
||||
- types Rust exacts de `ksp-program-api`, `ksp-materializer-api` et `ksp-store-api` ;
|
||||
- représentation ouverte/persistable des résultats Program ;
|
||||
- schémas SQL, transactions, claims/leases et pagination PostgreSQL ;
|
||||
- mécanisme IPC du premier manager de worker autonome ;
|
||||
- injection du contexte nécessaire aux `DomainProjector` stateful ;
|
||||
- éventuel orchestrateur commun uniquement si un besoin opérationnel concret apparaît.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Data, Materialization et Store
|
||||
|
||||
@@ -19,7 +19,7 @@ Il définit les frontières durables de données KSP et précise :
|
||||
- sémantique des notifications de données persistées ;
|
||||
- stabilité différente entre niveaux structurants et projections spécialisées.
|
||||
|
||||
Cette tranche ne détaille pas encore le lifecycle complet, batching, concurrence ou supervision des workers/jobs. Ces sujets sont déplacés vers `pre.007`.
|
||||
Le lifecycle complet, batching, concurrence, backlog et reprise des workers/jobs sont détaillés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
|
||||
|
||||
## Nomenclature des niveaux durables
|
||||
|
||||
@@ -555,7 +555,7 @@ Il ne doit pas être nécessaire de refaire toute la chaîne lorsqu'un niveau in
|
||||
|
||||
Les replays sont des **jobs bornés**, pas des modes cachés des workers live.
|
||||
|
||||
Les noms exacts des futurs jobs de replay sont reportés à `pre.007`.
|
||||
Les jobs de replay retenus sont `ksp-job-replay-core`, `ksp-job-replay-generic-materialization` et `ksp-job-replay-domain-projection`.
|
||||
|
||||
# Notifications de données persistées
|
||||
|
||||
@@ -649,7 +649,7 @@ broker externe
|
||||
|
||||
`ksp-store-lib` peut fournir PostgreSQL LISTEN/NOTIFY comme mécanisme de référence si cela répond au premier besoin.
|
||||
|
||||
Le choix détaillé des mécanismes, reprise, batching et multi-process est reporté à `pre.007`.
|
||||
Le mécanisme initial de référence et la reprise opérationnelle sont détaillés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
|
||||
|
||||
# Acquisition live et backfill
|
||||
|
||||
@@ -690,7 +690,7 @@ Chaque worker :
|
||||
- écrit seulement le niveau durable dont il est propriétaire ;
|
||||
- ne transforme pas silencieusement plusieurs frontières en une étape monolithique.
|
||||
|
||||
Le détail lifecycle, concurrence, batching, cursors, checkpoints et hot reconfiguration est reporté à `pre.007`.
|
||||
Le lifecycle, la concurrence, les cursors/checkpoints et la hot reconfiguration sont détaillés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
|
||||
|
||||
# Projections de trading et autres domaines
|
||||
|
||||
@@ -722,11 +722,12 @@ La première implémentation Store devra encore fixer :
|
||||
- conversion u64/slot/PostgreSQL ;
|
||||
- stratégie des migrations initiales.
|
||||
|
||||
`pre.007` doit préciser :
|
||||
Les sujets opérationnels worker/job ont été précisés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
|
||||
|
||||
- lifecycle des quatre workers ;
|
||||
- jobs de replay ;
|
||||
- checkpoint/backlog ;
|
||||
- batching/concurrence ;
|
||||
- mécanisme de notification de référence ;
|
||||
- processus/IPC selon les managers retenus.
|
||||
Restent à définir à l'implémentation :
|
||||
|
||||
- schémas SQL et contraintes exactes ;
|
||||
- format concret des DTO D1/D2/D3/D4 ;
|
||||
- claim/lease PostgreSQL ;
|
||||
- contexte des projectors stateful ;
|
||||
- mécanisme IPC des managers de services autonomes.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Acquisition, workers, jobs et pipelines spécialisés
|
||||
|
||||
@@ -23,7 +23,7 @@ Il transforme les frontières durables D1–D4 en modèle opérationnel et défi
|
||||
- hot reconfiguration du raw retriever ;
|
||||
- batching, backpressure et métriques opérationnelles minimales.
|
||||
|
||||
Les apps, managers desktop, IPC et orchestrateur global sont reportés à `pre.008`.
|
||||
Les apps spécialisées, services autonomes, control plane, scenarios et frontière IPC sont détaillés dans `010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`. Une application globale reste future ; un orchestrateur commun n'est pas une crate retenue actuellement.
|
||||
|
||||
# Principe : une frontière de processing, une logique réutilisable
|
||||
|
||||
@@ -901,4 +901,4 @@ Les premières implémentations doivent encore fixer :
|
||||
- politique précise de pause/resume des jobs ;
|
||||
- métriques/export telemetry au-delà des logs et health.
|
||||
|
||||
`pre.008` doit maintenant se concentrer sur apps, managers, scenarios, processus/IPC et orchestration globale.
|
||||
La couche supérieure est désormais cadrée dans `010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`. Le mécanisme IPC exact et l'éventuel orchestrateur restent à décider uniquement sur besoin concret.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/000-README.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Plans KSP
|
||||
|
||||
@@ -7,8 +7,11 @@ Ce répertoire contient les plans actifs ou historiques des versions et phases d
|
||||
|
||||
Un plan décrit le périmètre, les décisions déjà acquises, les questions ouvertes, les validations attendues et la prévision souple des prereleases. Il ne remplace pas le `ROADMAP.md`, qui reste global, ni les deltas qui enregistrent le travail réellement livré.
|
||||
|
||||
## Plan actif
|
||||
## Plans de référence
|
||||
|
||||
- [`001-V0_0_3_PLAN.md`](001-V0_0_3_PLAN.md) — plan de la phase de brainstorming et planification `0.0.3`.
|
||||
- [`001-V0_0_3_PLAN.md`](001-V0_0_3_PLAN.md) — plan de la phase fondatrice `0.0.3`, en clôture ;
|
||||
- [`002-FUNCTIONAL_RELEASE_SEQUENCE.md`](002-FUNCTIONAL_RELEASE_SEQUENCE.md) — séquence de référence des premières releases fonctionnelles, dont `0.1.1`.
|
||||
|
||||
Le préfixe numérique sert ici à maintenir le plan actif prioritaire après `000-README.md`. Lorsqu'un autre ordre devient préférable, la convention documentaire permet de le réorganiser explicitement.
|
||||
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.
|
||||
|
||||
Le préfixe numérique maintient un ordre documentaire explicite après `000-README.md`.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Plan KSP 0.0.3
|
||||
|
||||
@@ -157,13 +157,28 @@ Livré :
|
||||
|
||||
### `pre.010` — Clôture fondatrice
|
||||
|
||||
- relire les règles, architecture, roadmap, plans et IDEAS pour détecter les contradictions restantes ;
|
||||
- vérifier que la documentation racine/indexée disponible est cohérente ;
|
||||
- vérifier les versions de fichiers et le versionnement Cargo ;
|
||||
- effectuer les validations workspace applicables à la fondation ;
|
||||
- mettre à jour/nettoyer/archiver ce qui doit l'être ;
|
||||
- synchroniser le changelog si le fichier existe dans la base de travail ;
|
||||
- finaliser `prompts/001-V0_1_1_START_PROMPT.md` ;
|
||||
- produire le delta/release stable `0.0.3` et préparer le démarrage de `0.1.1`.
|
||||
Livré :
|
||||
|
||||
`pre.010` n'est pas une nouvelle tranche de brainstorming architectural. Une évolution de fond n'y est ouverte qu'en cas d'incohérence critique détectée pendant l'audit final.
|
||||
- reconstruction/audit de la fondation complète `0.0.2` + deltas `0.0.3` disponibles ;
|
||||
- correction des références documentaires obsolètes ;
|
||||
- correction des doublons normatifs `KSP-MAT-001/002` ;
|
||||
- remplacement des derniers termes `executor` devenus ambigus par `ProgramExecutionPreparer`/execution preparation ;
|
||||
- mise à jour des index docs/plans/prompts ;
|
||||
- finalisation de `prompts/001-V0_1_1_START_PROMPT.md` ;
|
||||
- audit automatique des headers, liens locaux et IDs de règles ;
|
||||
- passage Cargo à `0.0.3-pre.10`.
|
||||
|
||||
Les validations Cargo ont été tentées dans l'environnement de génération mais ne sont pas exécutables car la commande `cargo` n'y est pas installée.
|
||||
|
||||
Avant `0.0.3-rel.001`, exécuter sur le dépôt réel :
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo check --workspace
|
||||
cargo test --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
```
|
||||
|
||||
La publication stable `0.0.3-rel.001` passe ensuite `workspace.package.version` à `0.0.3`, marque la fondation terminée dans le roadmap et prépare le commit/tag stable `v0.0.3`.
|
||||
|
||||
`pre.010` clôt le brainstorming architectural. `rel.001` ne doit contenir aucune nouvelle architecture sauf correction bloquante issue des validations.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/RULES_KSP.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Règles spécifiques à KSP
|
||||
|
||||
@@ -32,7 +32,7 @@
|
||||
- **KSP-PROGRAM-002** — Le decoder vise toute surface techniquement décodable dont la définition est connue, y compris les formats anciens, obsolètes ou expérimentaux encore distinguables.
|
||||
- **KSP-PROGRAM-003** — Le statut `deprecated` concerne la capacité d'exécution, pas la capacité de décodage.
|
||||
- **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-005** — Une opération réellement deprecated mais toujours identifiable et techniquement préparabile peut rester supportée par son `ProgramExecutionPreparer`, avec statut/warning machine-readable et décision finale laissée à la policy supérieure.
|
||||
- **KSP-PROGRAM-006** — `ksp-program-lib` ne contient pas la politique de sécurité de production.
|
||||
- **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.
|
||||
@@ -139,10 +139,8 @@
|
||||
- **KSP-JOB-011** — Le backfill conserve un checkpoint de progression dans la source historique en plus des outcomes de persistence D1.
|
||||
- **KSP-JOB-012** — Replay normal/reprise et force replay sont deux intentions distinctes ; un force replay conserve provenance/historique et ne supprime pas silencieusement le résultat courant.
|
||||
|
||||
## Matérialisation et persistence
|
||||
## 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.
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/rules/VERSION_WORKFLOW.md -->
|
||||
<!-- version: 5 -->
|
||||
<!-- version: 6 -->
|
||||
|
||||
# Versionnement, sessions et livraisons
|
||||
|
||||
@@ -12,7 +12,7 @@ Les règles `VER-*` définissent la progression des versions KSP, les identifian
|
||||
- **VER-PROJECT-001** — `0.0.x` est la phase fondatrice : dépôt, squelette, règles, architecture, planification et préparation de la première phase fonctionnelle.
|
||||
- **VER-PROJECT-002** — `0.0.1` contient uniquement le `.gitignore` initial.
|
||||
- **VER-PROJECT-003** — `0.0.2` installe le squelette minimal, les règles initiales, `README.md`, `Cargo.toml`, `rustfmt.toml` et `clippy.toml`, sans développement métier.
|
||||
- **VER-PROJECT-004** — `0.0.3` et les versions fondatrices suivantes poursuivent le brainstorming, l'architecture, la nomenclature, le plan global et la préparation du prompt de `0.1.x`.
|
||||
- **VER-PROJECT-004** — `0.0.3` clôt la phase fondatrice avec l'architecture, la nomenclature, le plan global et le prompt de la première release fonctionnelle concrète.
|
||||
- **VER-PROJECT-005** — `0.1.x` ouvre la première phase de développement fonctionnel seulement après clôture de la session fondatrice.
|
||||
|
||||
## Version Cargo et identifiant de livraison
|
||||
@@ -62,7 +62,7 @@ Les règles `VER-*` définissent la progression des versions KSP, les identifian
|
||||
- **VER-SESSION-001** — Toute nouvelle session fonctionnelle commence par une phase de brainstorming puis une phase de planification avant toute modification de développement.
|
||||
- **VER-SESSION-002** — Après validation du plan, la session peut enchaîner développement, validations/tests, documentation finale puis préparation du prompt de la session suivante.
|
||||
- **VER-SESSION-003** — La session fondatrice actuelle remplace la phase de développement par la définition des règles, de l'architecture, du squelette et du plan nécessaires à KSP.
|
||||
- **VER-SESSION-004** — La session fondatrice doit se terminer avec un workspace initial cohérent, la documentation/règles nécessaires, un plan de poursuite et un prompt permettant d'ouvrir `0.1.x`.
|
||||
- **VER-SESSION-004** — La session fondatrice doit se terminer avec un workspace initial cohérent, la documentation/règles nécessaires, un plan de poursuite et un prompt permettant d'ouvrir la première release fonctionnelle ; pour la fondation actuelle, il s'agit de `0.1.1`.
|
||||
- **VER-SESSION-005** — Le changelog général, lorsqu'il existe, est synchronisé en fin de session à partir des deltas validés et ne remplace pas les deltas détaillés.
|
||||
|
||||
## Première et dernière prerelease d'une phase de développement
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: prompts/000-README.md -->
|
||||
<!-- version: 2 -->
|
||||
<!-- version: 3 -->
|
||||
|
||||
# Prompts KSP
|
||||
|
||||
@@ -17,8 +17,8 @@ La structure normative, le cycle de vie et les règles de dimensionnement des pr
|
||||
|
||||
Un prompt de prochaine grande phase est créé dès que sa direction devient suffisamment claire, puis maintenu comme brouillon vivant jusqu'à la clôture de la phase courante.
|
||||
|
||||
Le prompt `0.1.x` est commencé pendant `0.0.3`, mis à jour au fil des décisions, puis finalisé avant l'ouverture du développement fonctionnel.
|
||||
Le prompt générique `0.1.x` a été affiné pendant `0.0.3` puis remplacé par le prompt concret `0.1.1` lorsque la première release fonctionnelle a été sélectionnée.
|
||||
|
||||
## Documents
|
||||
|
||||
- [`001-V0_1_X_START_PROMPT.md`](001-V0_1_X_START_PROMPT.md) — brouillon vivant du prompt ouvrant le développement fonctionnel `0.1.x`.
|
||||
- [`001-V0_1_1_START_PROMPT.md`](001-V0_1_1_START_PROMPT.md) — prompt final ouvrant la première release fonctionnelle `0.1.1` après publication stable de `0.0.3`.
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
<!-- file: prompts/001-V0_1_1_START_PROMPT.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Prompt de démarrage KSP 0.1.1
|
||||
|
||||
**Status : Quasi-final — à confirmer pendant la clôture `0.0.3-pre.010`.**
|
||||
**Status : Final — à utiliser après validation et publication stable de `0.0.3`.**
|
||||
|
||||
## 1. Identité
|
||||
|
||||
@@ -38,7 +38,7 @@ Avant tout travail :
|
||||
- relire le delta final `0.0.3` et le prompt présent ;
|
||||
- vérifier que la version workspace est passée à la version/prerelease `0.1.1` appropriée au premier delta.
|
||||
|
||||
`0.0.3-pre.010` doit confirmer les références exactes de clôture.
|
||||
La session ne doit commencer que depuis la release stable/taguée `v0.0.3`.
|
||||
|
||||
## 4. Sources de vérité
|
||||
|
||||
|
||||
Reference in New Issue
Block a user