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 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.

Périmètre initial

À auditer précisément dans 0.1.1-pre.001, avec comme candidats acquis :

• type public commun ksp_core_lib::Error ;
• alias public commun Result<T> ou forme équivalente validée ;
• architecture d'erreur permettant aux domaines supérieurs d'ajouter du contexte sans faire connaître tous les futurs domaines à Core ;
• Program IDs fondamentaux appartenant à KSP Core ;
• primitives/identités réellement communes et déjà justifiées ;
• conventions de version/provenance N1 uniquement si un besoin concret existe ;
• exports crate-root et documentation publique ;
• tests unitaires/integration appropriés ;
• respect complet des règles Rust/workspace.

Dépendances

Core ne dépend pas de ksp-logging-lib, Config, Wallet, Store, Transport, Program ou Materializer.

Une primitive Solana/Anza officiellement stable peut être ajoutée seulement lorsqu'un item Core concret en a besoin.

solana-pubkey est un candidat naturel pour les Program IDs ; les autres primitives autorisées ne sont pas ajoutées par anticipation.

Hors scope

• logging ;
• configuration ;
• Tauri ;
• wallet/signing ;
• codecs wire ;
• decoders/Program registry ;
• transaction execution ;
• transport ;
• Store ;
• Materializer ;
• workers/jobs ;
• scenarios.

Lifecycle de la release

Le nombre de prereleases n'est pas figé avant pre.001.

Trajectoire candidate :

pre.001  brainstorming + audit + plan détaillé
pre.002  Error/Result + fondation API
pre.003  primitives/Program IDs réellement retenus
pre.004  compléments/tests/audits
pre.005  validation finale/docs/cleanup/prompt 0.1.2

Cette séquence est indicative. pre.001 peut la modifier.

0.1.2 — Logging foundation

Dépendances

ksp-logging-lib
    -> ksp-core-lib
    -> tracing
    -> tracing-appender
    -> tracing-subscriber

Mission

Faire de ksp-logging-lib la façade KSP unique de logging/tracing pour les composants runtime.

Périmètre candidat

• initialisation ;
• settings runtime propres au logging ;
• error, warn, info, debug, trace ;
• target/domain/component/champs structurés selon API validée ;
• fonctions, macros ou combinaison permettant de préserver correctement les callsites ;
• console/fichiers ;
• filtering ;
• appender/rotation selon besoin concret ;
• tests ;
• protection contre logging de secrets.

ksp-logging-lib ne dépend pas de ksp-config-lib.

Config pourra plus tard convertir ses documents résolus en settings de Logging.

0.1.3 — Configuration foundation

Dépendances candidates

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 KS_* / KB_* ;
• secret/public/debug exposure policy ;
• logging.config.json séparé ;
• schemas sous config/schemas/ ;
• examples sous config/.

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 :

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 :

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.

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.

Sélection de la première release

La première release fonctionnelle est :

0.1.1 — Core foundation

Le prompt de démarrage associé est :

prompts/001-V0_1_1_START_PROMPT.md

0.0.3-pre.010 doit seulement effectuer la clôture fondatrice, confirmer ce prompt et la base stable 0.0.3, sans rouvrir le découpage architectural sauf incohérence critique.