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

Plan KSP 0.0.3

Note de supersession — 0.2.0-pre.002
Ce document conserve le cadrage historique établi pendant 0.0.3. Les mentions ci-dessous de quatre pipelines fixes, de ksp-worker-generic-materializer, de ksp-worker-domain-projector ou d'un Core processing dépendant du décodage Program décrivent l'état de décision de cette ancienne release et ne constituent plus l'architecture courante. Depuis 0.2.0-pre.002, les documents normatifs/actifs sont docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md, docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md, docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md, docs/plans/007-V0_2_0_SERIES_PLANNING.md et les règles associées. Le modèle courant est RAW -> CORE -> DECODE -> SPECIALIZED, RAW/CORE ne dépendent pas d'un decoder Program, et les capacités de DECODE/SPECIALIZED sont introduites verticalement groupe par groupe.

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 à la clôture de 0.0.3 — historique

• 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

Livré :

• reconstruction/audit de la fondation complète 0.0.2 + deltas 0.0.3 disponibles ;
• correction des références documentaires obsolètes ;
• correction des doublons normatifs KSP-MAT-001/002 ;
• remplacement des derniers termes executor devenus ambigus par ProgramExecutionPreparer/execution preparation ;
• mise à jour des index docs/plans/prompts ;
• finalisation de prompts/001-V0_1_1_START_PROMPT.md ;
• audit automatique des headers, liens locaux et IDs de règles ;
• passage Cargo à 0.0.3-pre.10.

Les validations Cargo ont été tentées dans l'environnement de génération mais ne sont pas exécutables car la commande cargo n'y est pas installée.

Avant 0.0.3-rel.001, exécuter sur le dépôt réel :

cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets

La publication stable 0.0.3-rel.001 passe ensuite workspace.package.version à 0.0.3, marque la fondation terminée dans le roadmap et prépare le commit/tag stable v0.0.3.

pre.010 clôt le brainstorming architectural. rel.001 ne doit contenir aucune nouvelle architecture sauf correction bloquante issue des validations.

rel.001 — Publication stable 0.0.3

Validations exécutées localement sur la base 0.0.3-pre.10 :

cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets

Résultats communiqués :

• cargo fmt --all -- --check : succès ;
• cargo check --workspace : succès ;
• cargo test --workspace : succès, ksp-core-lib contient encore volontairement 0 test fonctionnel pendant la fondation ;
• doc-tests : succès, 0 test ;
• cargo clippy --workspace --all-targets : succès.

La correction locale d'alignement du tableau docs/architecture/004-COMPONENT_INVENTORY.md est intégrée formellement à la release ; son header a déjà été incrémenté à la version 10.

Publication :

workspace.package.version = "0.0.3"
delivery = 0.0.3-rel.001
stable tag = v0.0.3

La phase fondatrice est clôturée.

La prochaine release à ouvrir est :

0.1.1 — Core foundation

avec prompts/001-V0_1_1_START_PROMPT.md.