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

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), pre.005 (Execution/Policy) et pre.006 (Data/Materialization/Store) sont maintenant 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 — Data, Materialization et Store

Livré :

• nomenclature durable D1 Raw / D2 Core / D3 journal générique / D4 projections spécialisées ;
• D1/D2/D3 fortement stabilisables et D4 plus évolutif ;
• D3 confirmé comme journal durable obligatoire ;
• frontière ksp-materializer-api / ksp-materializer-lib sans dépendance Store ;
• capacités conceptuelles de matérialisation générique et projection de domaine ;
• ksp-store-api backend-agnostic et ksp-store-lib PostgreSQL de référence ;
• provenance et temporalités par niveau ;
• idempotence/versionnement processors ;
• replays indépendants D1 -> D2, D2 -> D3, D3 -> D4 ;
• notifications après commit comme wake-up uniquement, Store comme source de vérité ;
• même contrat D1 pour acquisition live et backfill ;
• D4 par faits canoniques plutôt que tables par protocole.

pre.007 — Acquisition, workers de processing et jobs

• détailler ksp-worker-raw-retriever ;
• détailler ksp-worker-core-processor ;
• détailler ksp-worker-generic-materializer ;
• détailler ksp-worker-domain-projector et réévaluer son nom ;
• détailler ksp-job-backfill ;
• définir les jobs de replay D1 -> D2, D2 -> D3, D3 -> D4 ;
• définir backlog/checkpoints/cursors ;
• traiter batching, concurrence, reprise et hot reconfiguration ;
• choisir le mécanisme de notification de référence sans en faire la source de vérité.

pre.008 — Applications, managers, scenarios et orchestration

• 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.009 — 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.010 — 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.