# 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) et `pre.007` (Acquisition/Workers/Jobs) 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--lib` ; les contrats publics extensibles utilisent `ksp--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, 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 ; - déterminer comment apps/managers pilotent workers et jobs sans fusionner leurs lifecycle APIs ; - inventorier les autres pipelines spécialisés seulement si un besoin concret apparaît. ### `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` ; - vérifier l'ordre réel core/logging/config/interface/program/store/transport/workers sans introduire de dépendances circulaires ; - 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.