369 lines
11 KiB
Markdown
369 lines
11 KiB
Markdown
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
|
|
<!-- version: 5 -->
|
|
|
|
# Séquence des releases fonctionnelles KSP
|
|
|
|
## Objet
|
|
|
|
Ce document formalise la sortie principale de `0.0.3-pre.009`.
|
|
|
|
Il transforme les séries fonctionnelles du roadmap en une première séquence de développement concrète sans prétendre connaître trop tôt tous les numéros des séries futures.
|
|
|
|
Principes :
|
|
|
|
- une série `X.Y.x` est une famille fonctionnelle ;
|
|
- une release concrète `X.Y.Z` est une unité de travail/session dimensionnée ;
|
|
- chaque release concrète possède ses propres prereleases ;
|
|
- une release trop grosse est scindée au lieu d'être forcée dans une session ;
|
|
- les numéros futurs sont confirmés lorsque leur série approche et que les dépendances réelles sont connues.
|
|
|
|
# Première série fonctionnelle : `0.1.x`
|
|
|
|
La série `0.1.x` construit les fondations N1 dans l'ordre de dépendances réel.
|
|
|
|
Séquence par défaut :
|
|
|
|
```text
|
|
0.1.1 ksp-core-lib
|
|
|
|
|
v
|
|
0.1.2 ksp-logging-lib
|
|
|
|
|
v
|
|
0.1.3 ksp-config-lib
|
|
|
|
|
v
|
|
0.1.4 ksp-app-config-desk
|
|
```
|
|
|
|
`0.1.1` et `0.1.2` sont fixées.
|
|
|
|
`0.1.3` et `0.1.4` sont la séquence par défaut. Si le `pre.001` de Config démontre qu'une seule release ne permet pas un développement propre, Config est scindé et les numéros suivants sont décalés.
|
|
|
|
## `0.1.1` — Core foundation
|
|
|
|
### Mission
|
|
|
|
Stabiliser `ksp-core-lib` comme fondation N1 minimale et durable.
|
|
|
|
Le Core possède uniquement les contrats réellement transversaux nécessaires aux couches supérieures.
|
|
|
|
### Surface stabilisée
|
|
|
|
`0.1.1` stabilise :
|
|
|
|
- `ksp_core_lib::ErrorCode`, `ErrorContext`, `Error` et `Result<T>` comme contrat d'erreur ouvert aux domaines supérieurs ;
|
|
- `ksp_core_lib::Pubkey` comme primitive Solana réexportée par Core ;
|
|
- 18 Program IDs fondamentaux possédés par KSP avec paires `PRGID_*` / `PRGIDPK_*` ;
|
|
- `declare_program_id!` pour construire la représentation texte et `Pubkey` depuis une déclaration canonique unique ;
|
|
- `ProgramIdEntry`, `ProgramIdFilter`, `ProgramIdKind` et le registre enumerable/recherchable ;
|
|
- des vues par domaine/famille/protocole et `native_program_ids()` sans registres secondaires ;
|
|
- une taxonomie extensible séparant notamment `subfamily` et `program_version` ;
|
|
- les réexports crate-root, rustdocs et tests publics correspondants.
|
|
|
|
### Dépendances
|
|
|
|
Core ne dépend pas de `ksp-logging-lib`, Config, Wallet, Store, Transport, Program ou Materializer.
|
|
|
|
La seule dépendance externe directe de `ksp-core-lib` à la clôture est `solana-pubkey`, déclarée au workspace avec la génération `^4.3`, `default-features = false`, puis héritée par la crate avec `.workspace = true`. Aucune feature optionnelle supplémentaire n'est activée dans `0.1.1`.
|
|
|
|
### Hors scope
|
|
|
|
- logging ;
|
|
- configuration ;
|
|
- Tauri ;
|
|
- wallet/signing ;
|
|
- codecs wire ;
|
|
- decoders/Program registry ;
|
|
- transaction execution ;
|
|
- transport ;
|
|
- Store ;
|
|
- Materializer ;
|
|
- workers/jobs ;
|
|
- scenarios.
|
|
|
|
### Lifecycle de la release
|
|
|
|
Trajectoire réellement suivie :
|
|
|
|
```text
|
|
pre.001 brainstorming + audit + plan détaillé
|
|
pre.001-fix.001/.002 corrections de cadrage Program IDs/taxonomie
|
|
pre.002 Error/Result + fondation API
|
|
pre.002-fix.001 corrections de tests/lints
|
|
pre.003 Pubkey + Program IDs
|
|
pre.003-fix.001 politique Cargo workspace + corrections Clippy
|
|
pre.004 intégration Core + audits
|
|
pre.005 validation finale/docs/cleanup/prompt 0.1.2
|
|
rel.001 publication stable validée de 0.1.1
|
|
```
|
|
|
|
## `0.1.2` — Logging foundation
|
|
|
|
### Mission
|
|
|
|
Faire de `ksp-logging-lib` la façade KSP unique de logging/tracing pour les composants runtime.
|
|
|
|
### Surface stabilisée
|
|
|
|
`0.1.2` stabilise :
|
|
|
|
- les macros KSP `error!`, `warn!`, `info!`, `debug!`, `trace!` avec `target:` KSP explicite et callsite consommateur préservé ;
|
|
- les spans KSP synchrones et l'instrumentation de futures async sans exposer `tracing` aux consumers ;
|
|
- `LoggingSettings`, niveaux, overrides par préfixe de target et lifecycle de spans ;
|
|
- `initialize()` unique et `reinitialize()` à chaud avec `LoggingGuard` ;
|
|
- le takeover des targets : targets externes silencieux par défaut, targets `ksp-*` gouvernés par la politique KSP ;
|
|
- console et fichier non bloquants, rotation, ownership des `WorkerGuard` et compteurs cumulés de lignes abandonnées ;
|
|
- stripping ANSI avant persistence fichier ;
|
|
- reconfiguration transactionnelle conservant l'ancien runtime en cas d'échec ;
|
|
- tests de saturation, concurrence/reload, lifecycle spans et instrumentation Tokio réelle ;
|
|
- audit d'ownership empêchant les autres crates workspace de dépendre directement de la stack `tracing*`.
|
|
|
|
### Dépendances runtime
|
|
|
|
```text
|
|
ksp-logging-lib
|
|
-> ksp-core-lib
|
|
-> tracing
|
|
-> tracing-appender
|
|
-> tracing-subscriber
|
|
```
|
|
|
|
Tokio est uniquement une dev-dependency de `ksp-logging-lib` pour les tests async réels et n'appartient pas à son graphe normal.
|
|
|
|
`ksp-logging-lib` ne dépend pas de `ksp-config-lib`. Config pourra convertir ses documents résolus en `LoggingSettings` puis utiliser le lifecycle public de Logging.
|
|
|
|
### Lifecycle de la release
|
|
|
|
Trajectoire réellement suivie :
|
|
|
|
```text
|
|
pre.001 brainstorming + audit + plan détaillé
|
|
pre.001-fix.001 corrections de cadrage takeover/reload/spans
|
|
pre.002 crate + settings + façade événements/spans
|
|
pre.002-fix.001 corrections tests/lints
|
|
pre.003 subscriber + takeover + console + reload
|
|
pre.003-fix.001 correction du montage reload/filter
|
|
pre.004 console/fichier non bloquants + guards + ANSI
|
|
pre.004-fix.001..004 corrections lifecycle, ANSI, takeover et Clippy
|
|
pre.005 robustesse, concurrence, saturation, audits
|
|
pre.005-fix.001 suppression du bruit console du stress test
|
|
pre.006 validation finale, Tokio dev-only, docs, prompt 0.1.3
|
|
pre.006-fix.001 correction documentaire du prompt Config
|
|
rel.001 publication stable validée de 0.1.2
|
|
```
|
|
|
|
## `0.1.3` — Configuration foundation
|
|
|
|
### Dépendances candidates
|
|
|
|
```text
|
|
ksp-config-lib
|
|
-> ksp-core-lib
|
|
-> ksp-logging-lib
|
|
```
|
|
|
|
### Mission
|
|
|
|
Introduire la configuration générale KSP.
|
|
|
|
Périmètre candidat à revalider dans son `pre.001` :
|
|
|
|
- documents spécialisés ;
|
|
- profils ;
|
|
- `default_profile` autonome ;
|
|
- valeurs globales hors profils lorsqu'elles ne varient pas ;
|
|
- résolution ;
|
|
- validation ;
|
|
- modification/sauvegarde ;
|
|
- variables d'environnement `KSP_*` / `KSPB_*` ;
|
|
- secret/public/debug exposure policy ;
|
|
- `logging.config.json` séparé ;
|
|
- vrais fichiers runtime sous `config/`, schemas sous `config/schemas/` et exemples sous `config/examples/` ;
|
|
- documents unitaires spécialisés + fichiers composites par application/exécutable ;
|
|
- ownership exclusif de `ksp-config-lib` sur lecture/résolution/validation/mutation des fichiers Config et variables d'environnement ;
|
|
- accès explicite aux secrets pour les surfaces de management autorisées.
|
|
|
|
### Règle de scission
|
|
|
|
Si le plan détaillé démontre que validation/schemas, résolution/profiles et mutation/persistence dépassent une release raisonnable, Config est réparti sur deux releases de `0.1.x`.
|
|
|
|
Aucun sous-périmètre n'est compressé artificiellement pour préserver le numéro `0.1.4` de l'application desktop.
|
|
|
|
## `0.1.4` — Config desktop par défaut
|
|
|
|
Sous réserve d'absence de scission de Config.
|
|
|
|
Mission :
|
|
|
|
```text
|
|
ksp-app-config-desk
|
|
-> ksp-config-lib
|
|
-> ksp-logging-lib
|
|
```
|
|
|
|
L'application doit valider réellement :
|
|
|
|
- lecture de documents ;
|
|
- profils/default profile ;
|
|
- résolution ;
|
|
- validation ;
|
|
- édition/sauvegarde ;
|
|
- env overrides exposables ;
|
|
- diagnostics/errors ;
|
|
- intégration logging ;
|
|
- conventions Tauri/DTO/TS-RS.
|
|
|
|
La logique Config reste dans `ksp-config-lib`.
|
|
|
|
# Règle Git à partir de `0.1.x`
|
|
|
|
À partir de la première release fonctionnelle, **chaque delta est commité**.
|
|
|
|
Exemples :
|
|
|
|
```text
|
|
0.1.1-pre.001
|
|
0.1.1-pre.002
|
|
0.1.1-pre.002-fix.001
|
|
...
|
|
0.1.1
|
|
```
|
|
|
|
Une étape intermédiaire erronée n'est pas supprimée de l'historique pour reconstruire artificiellement un développement parfait. Elle est corrigée par un delta/commit suivant.
|
|
|
|
Seul le commit de release stable reçoit le tag :
|
|
|
|
```text
|
|
v0.1.1
|
|
```
|
|
|
|
# Lifecycle standard d'une release fonctionnelle
|
|
|
|
## Première prerelease
|
|
|
|
Par défaut :
|
|
|
|
- relire la base validée ;
|
|
- brainstorming ;
|
|
- audit des besoins ;
|
|
- vérification des dépendances externes actuelles depuis les sources officielles lorsque concernées ;
|
|
- plan détaillé ;
|
|
- inventaire des fichiers/API touchés ;
|
|
- dimensionnement des prereleases ;
|
|
- décision explicite sur les hors-scope.
|
|
|
|
La première prerelease ne doit pas se transformer automatiquement en une grosse phase d'implémentation.
|
|
|
|
## Prereleases intermédiaires
|
|
|
|
Chaque prerelease porte un objectif borné et cohérent.
|
|
|
|
Une tranche de travail de planification/développement manifestement trop grosse est scindée.
|
|
|
|
## Dernière prerelease
|
|
|
|
Par défaut :
|
|
|
|
- validations complètes ;
|
|
- tests de conformité/audits ;
|
|
- documentation finale ;
|
|
- nettoyage/archivage ;
|
|
- changelog ;
|
|
- prompt de la release suivante ;
|
|
- vérification de cohérence des versions.
|
|
|
|
# Série `0.2.x` — ordre candidat uniquement
|
|
|
|
`0.2.x` ouvre les capacités Solana N2.
|
|
|
|
L'ordre exact des numéros n'est **pas figé** en `0.0.3`.
|
|
|
|
Ordre candidat à réévaluer à l'approche de la série :
|
|
|
|
```text
|
|
wallet foundation
|
|
-> wallet specialized app
|
|
|
|
on-chain transport foundation
|
|
-> specialized transport/demo validation
|
|
|
|
interface/wire foundation
|
|
-> first concrete Program surface
|
|
|
|
program-api / program-lib
|
|
-> first real decoder + ProgramExecutionPreparer + registry validation
|
|
|
|
execution-policy-api / execution-lib
|
|
-> first real execution cycle
|
|
|
|
scenario/demo validating the complete path
|
|
```
|
|
|
|
Wallet, Transport et Interface sont en grande partie indépendants ; leur ordre précis peut donc être réordonné selon le premier cas fonctionnel choisi.
|
|
|
|
`ksp-offchain-transport-lib` reste need-driven.
|
|
|
|
# Série `0.3.x` — ordre candidat uniquement
|
|
|
|
Direction :
|
|
|
|
```text
|
|
store-api + PostgreSQL store foundation
|
|
|
|
|
v
|
|
D1 raw persistence
|
|
|
|
|
v
|
|
specialized Store app
|
|
|
|
|
v
|
|
worker-api / job-api
|
|
|
|
|
v
|
|
raw-ingestion pipeline
|
|
|
|
|
+--> raw-retriever service
|
|
|
|
|
+--> backfill job
|
|
```
|
|
|
|
Les contrats Materializer et les frontières D2/D3/D4 sont introduits lorsque les sorties Program/Core réelles nécessaires existent.
|
|
|
|
Store/D1/acquisition peuvent donc être validés avant une matérialisation complète.
|
|
|
|
# Séries suivantes
|
|
|
|
Les directions restent celles du roadmap :
|
|
|
|
```text
|
|
0.4.x Core/SPL/metadata + scenarios/demos
|
|
0.5.x Anchor + protocoles trading
|
|
0.6.x processing autonome D1 -> D4
|
|
0.7.x Trading Intelligence
|
|
0.8.x+ trading opérationnel + explorers + expansion produits
|
|
```
|
|
|
|
Ces séries sont des objectifs fonctionnels, pas un calendrier contractuel.
|
|
|
|
# Progression de la série `0.1.x`
|
|
|
|
La première release fonctionnelle est :
|
|
|
|
```text
|
|
0.1.1 — Core foundation
|
|
```
|
|
|
|
Son prompt historique d'ouverture reste :
|
|
|
|
```text
|
|
prompts/001-V0_1_1_START_PROMPT.md
|
|
```
|
|
|
|
`0.1.1-rel.001` publie la surface Core stable après validation complète de `pre.005`. Le commit de release reçoit le tag `v0.1.1`. La release suivante s'ouvre avec :
|
|
|
|
```text
|
|
0.1.2 — Logging foundation
|
|
prompts/002-V0_1_2_START_PROMPT.md
|
|
```
|