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), pre.006 (Data/Materialization/Store), pre.007 (Acquisition/Workers/Jobs), pre.008 (Apps/Services/Scenarios/Control) et pre.009 (Functional Release Sequence) 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 monolithique, ksp-scenario-api, ksp-onchain-transport-api, ksp-offchain-transport-api ou ksp-wallet-api n'est prévu actuellement.
• Quatre pipelines spécialisés sont désormais retenus pour les frontières durables : raw ingestion, Core processing, generic materialization et domain projection.
• 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

Livré :

• quatre pipelines spécialisés réutilisant chaque frontière durable entre worker live et job ;
• ksp-worker-api maintenu comme lifecycle API continue ;
• ksp-job-api maintenu comme lifecycle API terminable séparée ;
• ksp-worker-raw-retriever avec hot reconfiguration desired/effective ;
• ksp-worker-core-processor, ksp-worker-generic-materializer, ksp-worker-domain-projector ;
• ksp-job-backfill strictement D1 ;
• ksp-job-replay-core, ksp-job-replay-generic-materialization, ksp-job-replay-domain-projection ;
• backlog par input + processor/version/capability ;
• processing outcomes explicites même sans output ;
• claim/lease et reprise après crash ;
• at-least-once + idempotence ;
• replay normal vs force replay ;
• PostgreSQL LISTEN/NOTIFY comme wake-up initial de référence + periodic polling ;
• batching/concurrence bornés et principe de backpressure observable mais non automatique.

pre.008 — Applications, services, scenarios et control plane

Livré :

• applications spécialisées prioritaires sur toute future application globale ;
• future application globale conservée comme idée uniquement ;
• workers confirmés comme services/processus indépendants ;
• direction de packaging : package worker avec cible bibliothèque réutilisable + binaire autonome mince ;
• aucun worker concret ne dépend directement d'un autre worker ;
• data plane D1–D4 séparé du control plane ;
• ksp-worker-control-lib comme gouvernance réutilisable ;
• sémantique Worker indépendante du transport local/IPC ;
• aucun ksp-ipc-api générique créé prématurément ;
• aucun ordre global strict de démarrage figé ;
• scenarios exécutés dans ksp-scenario-<domain>-lib, jamais dans l'app desktop ;
• docs/rules/SCENARIO_CONVENTION.md comme norme souple ;
• applications scenario demo minces et appelables via la crate scenario ;
• ksp-orchestrator-lib conservé uniquement comme concept futur.

pre.009 — Plan des premières releases fonctionnelles

Livré :

• docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md ;
• 0.1.1 sélectionnée comme première release fonctionnelle ;
• 0.1.1 = ksp-core-lib ;
• 0.1.2 = ksp-logging-lib ;
• 0.1.3 = ksp-config-lib par défaut ;
• 0.1.4 = ksp-app-config-desk par défaut ;
• règle de scission de Config si son pre.001 démontre une charge excessive ;
• ordre candidat, volontairement non numéroté finement, pour 0.2.x et 0.3.x ;
• lifecycle standard des releases fonctionnelles ;
• chaque delta commité à partir de 0.1.x ;
• seul le commit stable reçoit le tag vX.Y.Z ;
• brouillon générique V0_1_X remplacé par le prompt quasi-final V0_1_1.

pre.010 — Clôture fondatrice

• relire les règles, architecture, roadmap, plans et IDEAS pour détecter les contradictions restantes ;
• vérifier que la documentation racine/indexée disponible est cohérente ;
• vérifier les versions de fichiers et le versionnement Cargo ;
• effectuer les validations workspace applicables à la fondation ;
• mettre à jour/nettoyer/archiver ce qui doit l'être ;
• synchroniser le changelog si le fichier existe dans la base de travail ;
• finaliser prompts/001-V0_1_1_START_PROMPT.md ;
• produire le delta/release stable 0.0.3 et préparer le démarrage de 0.1.1.

pre.010 n'est pas une nouvelle tranche de brainstorming architectural. Une évolution de fond n'y est ouverte qu'en cas d'incohérence critique détectée pendant l'audit final.