khadhroony-solana-project/docs/plans/001-V0_0_3_PLAN.md

<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
<!-- version: 9 -->

# Plan KSP 0.0.3

## Mission

Transformer le brainstorming KSP en architecture, règles, inventaire et plan suffisamment précis pour ouvrir la première série fonctionnelle `0.1.x` sans développement fonctionnel prématuré.

## État courant

- `pre.001` — base de planification stabilisée et commitée ;
- `pre.002` — inventaire initial des composants ;
- `pre.003` — graphe de dépendances, correction de l'inventaire et stabilisation des frontières de composition.

Les tranches `pre.004` (Wire/Program) et `pre.005` (Execution/Policy) sont maintenant cadrées/livrées séparément afin de conserver des prereleases de planification bornées.

## Décisions structurantes actuelles

- `0.1.x`, `0.2.x`, etc. sont des séries fonctionnelles, pas des unités de session.
- Chaque release concrète d'une série est dimensionnée séparément.
- Les bibliothèques d'implémentation utilisent `ksp-<role>-lib` ; les contrats publics extensibles utilisent `ksp-<domain>-api`.
- Program, Materializer et Store ont un couple API/implémentation séparé.
- Workers et jobs ont des lifecycle APIs distinctes, sans parent commun.
- `ksp-worker-raw-retriever` réalise uniquement l'acquisition raw live/quasi-live.
- `ksp-job-backfill` réalise l'acquisition historique à la demande.
- Le processing futur est séparé entre `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector`.
- `ksp-worker-control-lib` est la gouvernance commune des workers ; aucune `ksp-job-control-lib` n'est prévue actuellement.
- `ksp-execution-policy-api` est retenu.
- `ksp-execution-lib` est retenu comme orchestration spécialisée et dépend de `ksp-program-api`, pas de `ksp-program-lib`.
- `ksp-program-lib` ne dépend ni du wallet ni du transport.
- `ksp-materializer-lib` ne dépend pas du store.
- `ksp-store-api` reste indépendant de Program/Materializer/Transport.
- Les workers/jobs spécialisés convertissent explicitement les modèles entre transport, processing et persistence.
- `ksp-store-api` possède les notifications canoniques de données persistées ; leur transport concret reste séparé.
- Aucun `ksp-data-api`, `ksp-pipeline-lib`, `ksp-scenario-api`, `ksp-onchain-transport-api`, `ksp-offchain-transport-api` ou `ksp-wallet-api` n'est prévu actuellement.
- Les scenarios restent des crates spécialisées régies d'abord par une norme souple.

## Prévision souple des prereleases restantes

### `pre.003` — Graphe de dépendances et correction de l'inventaire

Livré :

- `docs/architecture/005-DEPENDENCY_GRAPH.md` ;
- graphe Program/Execution/Policy ;
- graphe Materializer/Store ;
- graphe Worker/Job ;
- conversion explicite des modèles aux frontières ;
- dépendances interdites et prévention des cycles ;
- correction de `004-COMPONENT_INVENTORY.md` ;
- suppression des décisions négatives présentées à tort comme tâches du roadmap.

### `pre.004` — Wire et Program

Livré :

- propriété et rôle de `ksp-interface-lib` ;
- propriété des codecs wire ;
- politique anti-doublons de générations et sélection/réimplémentation des interfaces externes ;
- API Program ouverte ;
- familles de decoders par capacité ;
- `ProgramExecutionPreparer` à la place d'un executor transactionnel ambigu ;
- statut lifecycle machine-readable pour les opérations anciennes/abandonnées ;
- registry extensible official + external ;
- organisation `domain -> program/protocol -> capability` ;
- workflow d'une implémentation externe avant intégration officielle.

### `pre.005` — Execution et Policy

Livré :

- `ksp-execution-policy-api` comme contrat de décision obligatoire pour une exécution réelle ;
- policy multi-checkpoints ;
- séparation stricte entre décision policy et actions wallet/réseau/UI ;
- `ksp-execution-lib` consommant `PreparedProgramExecution` sans dépendre de `ksp-program-lib` ;
- distinction Program constraints / caller options / policy constraints ;
- wallet/signers et provider sélectionnés par la composition supérieure ;
- simulation, signature, submission et confirmation orchestrées avec les primitives des libs propriétaires ;
- distinction retry transport / retry lifecycle d'exécution ;
- approbation externe suspendue/reprenable ;
- résultat d'exécution indépendant du Store ;
- `ksp-logging-lib` confirmé comme façade unique tracing du runtime KSP, avec dépendance possible vers Core pour `Error`/`Result`.

### `pre.006` — Données, store et acquisitions

- détailler `ksp-materializer-api` / `ksp-materializer-lib` ;
- détailler `ksp-store-api` / `ksp-store-lib` ;
- finaliser modèles raw/Core/generic/domain ;
- détailler notifications et mécanismes de diffusion possibles ;
- détailler W1 et backfill ;
- cadrer les workers de processing ;
- revisiter niveaux durables, replay, provenance et idempotence.

### `pre.007` — Applications, workers, jobs, scenarios et pipelines spécialisés

- formaliser les apps spécialisées ;
- détailler `ksp-worker-control-lib` ;
- définir la norme des crates scenario et leurs apps demo ;
- traiter les processus/IPC/managers ;
- cadrer l'orchestrateur futur ;
- inventorier les pipelines spécialisés réellement nécessaires.

### `pre.008` — Plan des premières releases fonctionnelles

- transformer les séries `0.1.x+` en premières releases concrètes ;
- dimensionner chaque release concrète ;
- choisir la première release `0.1.N` ;
- transformer le brouillon de prompt en prompt quasi-final de cette release concrète.

### `pre.009` — Clôture fondatrice

- validations finales de cohérence ;
- documentation/nettoyage/archivage ;
- synchronisation du changelog si applicable ;
- finalisation du prompt de la première release fonctionnelle.

Le nombre de prereleases reste révisable si une tranche dépasse le budget de planification ou si une frontière supplémentaire doit être étudiée.