khadhroony-solana-project/docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md

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 :

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, 0.1.2, 0.1.3 et 0.1.4 sont désormais des releases stables.

0.1.4 — ksp-app-config-desk établit le modèle de référence des futures applications Tauri KSP sans déplacer la logique Config dans l'application. Sa matrice finale a été validée avant rel.001, avec le build Tauri exécuté en dernière opération.

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 :

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

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 :

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 stabilisées

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 :

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 les compositions génériques par file_id; pre.010 le snapshot process + .env, .env.example et le resolver ${...}; pre.011 la sensibilité, les valeurs réelle/sûre, la redaction et la provenance enrichie; pre.012 l'adapter Config -> Logging et la validation effective des chemins; pre.013 management + persistence JSON/.env; pre.014 les audits exécutables d'ownership et la couverture automatique de .env.example; pre.015 la documentation durable et le prompt 0.1.4, complétés par deux fixes documentaires sur les validations et le modèle Tauri. rel.001 publie cette surface sous 0.1.3 stable.

Trajectoire réellement suivie :

pre.001                  brainstorming + audit + plan détaillé
pre.001-fix.001..003     corrections de cadrage, file_id/bootstrap et granularité
pre.002                  crate Config + bootstrap cfgpath/schemapath
pre.002-fix.001          correction de la première tranche Config
pre.003                  registre file_id + --filemap
pre.004                  Logging contracts/settings multi-output
pre.005                  Logging runtime multi-sink + routing level/target/formats
pre.005-fix.001          correction du test JSON runtime
pre.006                  Logging routing structuré domain
pre.007                  moteur JSON/JSON Schema + std.logging.json
pre.008                  globals + profils + default_profile
pre.009                  compositions génériques par file_id
pre.009-fix.001          correction Clippy du test composite
pre.010                  process env + .env + placeholders + .env.example
pre.010-fix.001          correction des racines de fixtures de test
pre.011                  sensibilité + real/safe/provenance
pre.011-fix.001          correction Clippy du test de provenance
pre.012                  adapter Config -> Logging
pre.013                  management + persistence JSON/.env
pre.013-fix.001          correction de syntaxe du warning persistence
pre.014                  ownership audits + robustesse
pre.015                  clôture/docs/prompt 0.1.4
pre.015-fix.001          règles validation/docs + modèle Tauri/PRESENTATION
pre.015-fix.002          tracing Tauri + critères fonctionnels de clôture 0.1.4
rel.001                  publication stable validée de 0.1.3

0.1.4 — Config desktop par défaut

0.1.4-pre.001 ouvre désormais cette release par l'audit et le plan détaillé :

docs/plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md

Mission :

ksp-app-config-desk
    -> ksp-config-lib
    -> ksp-logging-lib

L'application doit valider réellement :

• inventaire des documents Config enregistrés ;
• diagnostics JSON/schema/sémantiques/effective ;
• inspection puis réparation validée d'un source invalide ;
• profils/default profile et provenance ;
• environnement desired/effective/shadow ;
• mutation .env exclusivement via Config ;
• reveal Secret explicitement privilégié et séparé ;
• édition typée de plusieurs profils Logging ;
• profil mono-fichier ;
• profil multi-fichiers avec console ;
• sauvegarde séparée de l'activation runtime ;
• hot reload Logging observable sans redémarrage ;
• conservation du runtime précédent lorsqu'un reload échoue ;
• conventions Tauri/DTO/TS-RS servant de référence aux futures apps KSP.

L'audit pre.001 révèle deux extensions bornées à apporter d'abord à ksp-config-lib : une vue publique des descripteurs du registre et une frontière de sauvegarde d'un source candidat qui reste entièrement parsé, validé et persisté atomiquement par Config. L'application ne doit pas contourner ces manques par une liste parallèle de file_id ou par du filesystem direct.

Le shell retenu est une fenêtre principale de management plus splash, avec Vanilla TypeScript/Vite/SCSS/Bootstrap/Font Awesome. Aucune vue de présentation n'est retenue en 0.1.4, donc aucun PRESENTATION.md ni markdown-it n'est prévu.

La logique Config reste dans ksp-config-lib et le subscriber/runtime tracing reste dans ksp-logging-lib.

0.1.4-rel.001 publie cette surface sous 0.1.4 stable après validation complète de pre.019 et de son fix documentaire.

Règle Git à partir de 0.1.x

À partir de la première release fonctionnelle, chaque delta est commité.

Exemples :

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 :

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 :

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 :

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 :

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 :

0.1.1 — Core foundation

Son prompt historique d'ouverture reste :

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 :

0.1.2 — Logging foundation
prompts/002-V0_1_2_START_PROMPT.md

Ouverture de 0.2.0

Après publication stable de 0.1.4, la session suivante s’ouvre avec :

0.2.0-pre.001
prompts/005-V0_2_0_START_PROMPT.md

0.2.0 est une release intermédiaire de cadrage de la série 0.2.x. Sa mission n'est pas de choisir immédiatement un premier composant N2 à implémenter, mais de reprendre méthodiquement les capacités pertinentes de khadhroony-bot3 et de définir le plan de migration/refondation de la série.

La série 0.2.0 doit notamment produire :

• un inventaire des fonctionnalités khadhroony-bot3 pertinentes pour 0.2.x ;
• pour chaque capacité, une décision explicite reprendre / adapter / refondre / abandonner / ajouter ;
• les écarts entre les contrats historiques et les règles KSP déjà stabilisées en 0.1.x ;
• une cartographie des dépendances entre Wallet, transport on-chain, Interface/wire, Program API/Program, policy/execution et les éventuels besoins off-chain ;
• les nouvelles fonctionnalités nécessaires qui n'existaient pas dans bot3 ou dont le contrat doit être modifié ;
• le découpage concret du reste de 0.2.x en releases bornées 0.2.1, 0.2.2, etc., avec ordre, objectifs, dépendances, hors-périmètre et critères de clôture ;
• le prompt de démarrage de la première release fonctionnelle résultant de ce découpage.

Le document directeur attendu pour cette session est docs/plans/007-V0_2_0_SERIES_PLANNING.md. Les numéros et périmètres des releases 0.2.1+ ne deviennent contractuels qu'après validation de ce plan.