400 lines
14 KiB
Markdown
400 lines
14 KiB
Markdown
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
|
||
<!-- version: 15 -->
|
||
|
||
# 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.
|
||
|
||
Le `0.1.3-pre.001`, corrigé par `pre.001-fix.001`, `pre.001-fix.002` puis `pre.001-fix.003`, a revalidé ce périmètre et décidé qu'il tient dans une seule release à condition de limiter le premier cycle au socle générique, au document Logging, à la composition, à l'environnement KSP/KSPB, aux surfaces d'accès et à la persistence autorisée. Le plan normatif détaillé est `docs/plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`.
|
||
|
||
Périmètre retenu :
|
||
|
||
- registre logique `file_id -> filename` des fichiers Config/schemas connus, avec mappings par défaut surchargeables au bootstrap ;
|
||
- bootstrap non récursif `--cfgpath` / `--schemapath` avec défauts codés en dur `config` / `config/schemas` ;
|
||
- override répétable des filenames par `--filemap=<file_id>=<filename>` ;
|
||
- 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_*`, résolues exclusivement par Config ;
|
||
- priorité process env > `.env` > fallback `${NAME:-fallback}` ;
|
||
- propagation de la sensibilité et représentation sûre/redacted des valeurs dérivées de `*_SECRET_*` ;
|
||
- secret/public/debug exposure policy ;
|
||
- premier document spécialisé concret `config/std.logging.json`, identifié logiquement par `cfg.std.logging` et validé par `schema.std.logging` ;
|
||
- 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, avec références inter-document par `file_id` et non par filename ;
|
||
- 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 ;
|
||
- modèle Logging non régressif : console configurable et plusieurs sinks fichier/routings ; les capacités manquantes de `ksp-logging-lib 0.1.2` sont complétées dans Logging sans dépendance inverse vers Config.
|
||
|
||
### Décision de scission
|
||
|
||
Le `pre.001` ne scinde pas Config : `0.1.3` reste une release unique et `0.1.4` reste réservée à `ksp-app-config-desk`.
|
||
|
||
Cette décision repose sur l'absence volontaire de documents Transport/Wallet/Store/Execution et de watcher générique dans le premier cycle. Si une tranche ultérieure révèle une contrainte technique majeure réellement non bornable, la séquence peut encore être corrigée par un delta explicite plutôt que de comprimer artificiellement le périmètre.
|
||
|
||
Prévision souple regranularisée par `pre.001-fix.003`, puis scindée à nouveau pendant `pre.005` afin de traiter `domain` comme un champ structuré distinct :
|
||
|
||
```text
|
||
pre.002 crate Config + bootstrap cfgpath/schemapath
|
||
pre.003 registre file_id -> filename + --filemap
|
||
pre.004 Logging : contrats/settings multi-output
|
||
pre.005 Logging : runtime multi-sink + level/target/formats
|
||
pre.006 Logging : routing structuré domain
|
||
pre.007 JSON/JSON Schema + std.logging.json
|
||
pre.008 globals + profils + default_profile
|
||
pre.009 compositions génériques par file_id
|
||
pre.010 .env + process env + resolver ${...}
|
||
pre.011 sensibilité + real/safe/provenance
|
||
pre.012 adapter Config -> Logging
|
||
pre.013 management + persistence JSON/.env
|
||
pre.014 ownership audits + robustesse
|
||
pre.015 clôture
|
||
```
|
||
|
||
Cette prévision n'est pas un plafond : chaque prerelease doit rester une petite tranche, avec scission explicite si l'objectif dépasse environ 15–20 minutes de travail effectif.
|
||
|
||
`pre.006` a fermé le routing Logging structuré `domain`; `pre.007` a livré le moteur JSON/JSON Schema et `std.logging.json`; `pre.008` a ajouté la résolution générique globals/profils/`default_profile`; `pre.009` a ajouté les compositions génériques par `file_id`, avec `schema.composite` mais sans composite runtime fictif; `pre.010` ajoute le snapshot process + `.env`, `.env.example` et le resolver `${...}`. Après validation utilisateur, `pre.011` ajoutera sensibilité, valeur réelle/sûre et provenance enrichie.
|
||
|
||
## `0.1.4` — Config desktop par défaut
|
||
|
||
La décision `0.1.3-pre.001` conserve cette release comme étape suivante par défaut.
|
||
|
||
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. La cible de dimensionnement KSP est d'environ 15–20 minutes de travail effectif par prerelease ; ce budget est un garde-fou de granularité, pas une raison pour comprimer le périmètre.
|
||
|
||
## 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
|
||
```
|