227 lines
11 KiB
Markdown
227 lines
11 KiB
Markdown
<!-- file: docs/plans/001-V0_0_3_PLAN.md -->
|
||
<!-- version: 17 -->
|
||
|
||
# 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 :
|
||
|
||
```bash
|
||
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` :
|
||
|
||
```bash
|
||
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 :
|
||
|
||
```text
|
||
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 :
|
||
|
||
```text
|
||
0.1.1 — Core foundation
|
||
```
|
||
|
||
avec `prompts/001-V0_1_1_START_PROMPT.md`.
|