v0.0.3-pre.010

docs/architecture/002-LAYERS_AND_DEPENDENCIES.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/002-LAYERS_AND_DEPENDENCIES.md -->
-<!-- version: 4 -->
+<!-- version: 5 -->
 
 # Couches et dépendances KSP
 
@@ -32,7 +32,7 @@ Une bibliothèque N1 ne doit pas dépendre d'une fonctionnalité métier située
 
 N2 regroupe les capacités réutilisables opérant sur Solana au-dessus des fondations.
 
-Le nom `ksp-program-lib` est retenu pour la future bibliothèque propriétaire du traitement des programmes : décodage et opérations techniquement constructibles/exécutables. Elle doit s'appuyer sur `ksp-interface-lib` plutôt que faire porter les contrats wire aux applications.
+Le nom `ksp-program-lib` est retenu pour la bibliothèque propriétaire du traitement des programmes : décodage et préparation technique d'opérations via `ProgramExecutionPreparer`. Elle doit s'appuyer sur `ksp-interface-lib` plutôt que faire porter les contrats wire aux applications.
 
 Les autres responsabilités N2 candidates comprennent notamment :
 
@@ -72,11 +72,11 @@ W1 :
 - ne décide pas de l'utilisation métier des données collectées ;
 - doit pouvoir faire évoluer à chaud ce qu'il écoute, rapatrie ou stocke selon les mécanismes de configuration/commande qui seront définis.
 
-Les consommateurs des notifications W1 décident eux-mêmes s'ils doivent décoder, matérialiser ou effectuer un autre traitement.
+Les notifications W1 servent de wake-up. Les workers/jobs downstream reconstruisent leur backlog depuis le Store et appliquent les pipelines spécialisés correspondant aux frontières D1 -> D2 -> D3 -> D4.
 
 ### Workers de processing futurs
 
-Le processing continu n'est plus modélisé comme un unique W2. La direction actuelle sépare `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector` afin de respecter les frontières durables D1 Raw -> D2 Core -> D3 journal de matérialisation générique -> D4 projections de domaine. Leur détail sera repris dans la tranche consacrée aux workers/data.
+Le processing continu n'est plus modélisé comme un unique W2. Il sépare `ksp-worker-core-processor`, `ksp-worker-generic-materializer` et `ksp-worker-domain-projector` afin de respecter les frontières durables D1 Raw -> D2 Core -> D3 journal de matérialisation générique -> D4 projections de domaine. Le lifecycle, backlog, claim/lease et replay sont détaillés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
 
 ## N4 — Exécutables
 
@@ -141,7 +141,7 @@ Les workers sont différents des interfaces utilisateur. Ils peuvent contenir l'
 
 Un worker doit néanmoins consommer les bibliothèques KSP propriétaires des contrats Solana et ne doit pas dépendre directement de crates Solana/protocoles externes.
 
-Les premiers managers de workers peuvent être spécialisés et séparés. Un orchestrateur global sera introduit ultérieurement lorsque plusieurs workers/managers justifieront réellement cette abstraction.
+Les premiers managers de workers sont spécialisés et séparés. Une application globale est un produit futur, tandis qu'un orchestrateur commun reste une abstraction à réévaluer seulement lorsqu'un besoin opérationnel concret le justifie.
 
 ## Firewall des dépendances externes
 
@@ -182,7 +182,7 @@ Les contrats minimaux entre couches doivent être définis suffisamment tôt pou
 Ce principe s'applique notamment aux futurs :
 
 - decoders ;
-- executors/constructeurs d'opérations ;
+- `ProgramExecutionPreparer` / constructeurs d'opérations ;
 - materializers ;
 - store/repositories ;
 - transports ;
@@ -194,9 +194,9 @@ Il ne signifie pas qu'il faut implémenter prématurément toutes les fonctionna
 
 ## Questions encore ouvertes
 
-- représentation interne exacte du type d'erreur commun KSP ;
-- découpage interne précis de `ksp-program-lib` ;
-- politique de sécurité/exécution située au-dessus de `ksp-program-lib` ;
-- position précise du pipeline et du futur orchestrateur ;
+- représentation interne exacte du type d'erreur commun KSP, à traiter dès `0.1.1-pre.001` ;
+- types publics précis de `ksp-program-api` et format ouvert/persistable des résultats décodés ;
 - méthode de conformité wire contre les projets externes ;
-- graphe de dépendances précis crate par crate.
+- mécanisme IPC du premier manager de worker autonome ;
+- besoins de contexte des futurs `DomainProjector` stateful ;
+- nécessité réelle d'un orchestrateur commun lorsque plusieurs services/managers existeront.

docs/architecture/004-COMPONENT_INVENTORY.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/004-COMPONENT_INVENTORY.md -->
-<!-- version: 8 -->
+<!-- version: 10 -->
 
 # Inventaire initial des composants KSP
 
@@ -133,7 +133,7 @@ Ces modèles :
 - ne réalisent aucun décodage métier/protocolaire ;
 - doivent être facilement et explicitement convertibles par `ksp-worker-raw-retriever` vers les modèles raw persistants de `ksp-store-api`.
 
-Le détail de cette frontière de conversion est reporté à `pre.003/pre.005`.
+Les principes de cette frontière sont désormais fixés : transport et Store restent indépendants, et la conversion explicite transport -> D1 appartient au pipeline/composant de composition. Les DTO exacts seront définis avec les premières implémentations Transport/Store.
 
 ## Transport off-chain
 
@@ -167,7 +167,7 @@ Elle doit pouvoir être consommée par :
 
 - une application desktop manager spécialisée ;
 - une future application globale ;
-- un futur orchestrateur ;
+- un éventuel orchestrateur commun si un besoin opérationnel concret le justifie ;
 - des tools/tests lorsque pertinent.
 
 Les applications restent des interfaces et ne réimplémentent pas elles-mêmes registre, dispatch start/stop, agrégation d'état ou reconfiguration générique.
@@ -334,11 +334,11 @@ Le graphe confirme les principes suivants :
 - aucun `ksp-data-api` global n'est introduit ;
 - `ksp-worker-control-lib` est retenu comme gouvernance workers réutilisable ; aucune `ksp-job-control-lib` n'est retenue.
 
-## Questions reportées aux prereleases suivantes
+## Questions restantes après la fondation
 
-- `pre.004` : forme exacte du contrat entre program preparation, execution policy, wallet et transport ;
-- `pre.004` : types publics précis de `ksp-program-api` et policy ;
-- `pre.005` : types publics de transport on-chain et conversion vers les DTO raw de `ksp-store-api` ;
-- `pre.005` : modèles materializer/store, notifications, replay et provenance ;
+- types Rust exacts des contrats ouverts de `ksp-program-api` ;
+- DTO exacts des modèles transport et D1/D2/D3/D4 avec les premières implémentations concernées ;
+- schémas SQL, indexes, claims/leases et pagination du Store PostgreSQL ;
 - première implémentation manager/service : mécanisme IPC et proxy distant Worker ;
-- futur : orchestrateur/application globale seulement lorsqu'un besoin opérationnel concret le justifie.
+- contexte requis par les projectors stateful ;
+- futur : orchestrateur commun seulement si un besoin opérationnel concret le justifie ; l'application globale reste un produit futur après validation des apps spécialisées.

docs/architecture/005-DEPENDENCY_GRAPH.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/005-DEPENDENCY_GRAPH.md -->
-<!-- version: 6 -->
+<!-- version: 7 -->
 
 # Graphe de dépendances KSP
 
@@ -144,14 +144,17 @@ ksp-program-lib
 
 Il est également le propriétaire candidat du **contrat d'opération préparée** produit par la sémantique programme et consommé par la couche d'exécution.
 
-Noms exacts à définir en `pre.004`, par exemple conceptuellement :
+Le contrat de préparation retenu est centré sur :
 
 ```text
-PreparedProgramOperation
-ProgramExecutionPlan
+ProgramExecutionRequest
+        ↓
+ProgramExecutionPreparer
+        ↓
+PreparedProgramExecution
 ```
 
-Le choix du nom/type final n'est pas décidé ici.
+Les champs Rust exacts restent à définir avec la première implémentation, sans rouvrir la séparation préparation/exécution.
 
 ## Interdictions Program
 
@@ -456,7 +459,7 @@ notify
 
 Le payload privilégie une référence durable compacte.
 
-Le mécanisme concret peut être channel, PostgreSQL LISTEN/NOTIFY, IPC ou broker. Le choix détaillé est reporté à `pre.007`.
+Le contrat reste indépendant du mécanisme. PostgreSQL `LISTEN/NOTIFY` est retenu comme mécanisme initial de référence de wake-up, combiné à un polling périodique du backlog.
 
 ---
 
@@ -849,29 +852,13 @@ Les conversions entre Program/Materializer/Store ne sont pas résolues par des d
 
 ---
 
-# Questions reportées
+# Questions restantes
 
-`pre.004` doit détailler :
+Les grandes frontières de dépendances sont désormais fixées. Restent à résoudre avec les premières implémentations :
 
-- noms/types exacts des entrées/sorties de `ksp-program-api` ;
-- forme exacte de l'opération préparée ;
-- appel/injection entre program implementation et `ksp-execution-lib` ;
-- contrat exact de `ksp-execution-policy-api` ;
-- frontière entre préparation, policy, simulation, signature, envoi et confirmation.
-
-`pre.005` doit détailler :
-
-- DTO raw/Core/materialization/projection du store ;
-- entrées/sorties `ksp-materializer-api` ;
-- conversion Core runtime <-> store Core ;
-- notifications et transport de notifications ;
-- niveaux durables/replay/idempotence/provenance ;
-- rôle précis des deux workers de matérialisation.
-
-`pre.006` doit détailler :
-
-- managers spécialisés ;
-- processus/IPC éventuels ;
-- norme des scenarios ;
-- apps demo ;
-- orchestrateur futur et pipelines spécialisés.
+- types Rust exacts de `ksp-program-api`, `ksp-materializer-api` et `ksp-store-api` ;
+- représentation ouverte/persistable des résultats Program ;
+- schémas SQL, transactions, claims/leases et pagination PostgreSQL ;
+- mécanisme IPC du premier manager de worker autonome ;
+- injection du contexte nécessaire aux `DomainProjector` stateful ;
+- éventuel orchestrateur commun uniquement si un besoin opérationnel concret apparaît.

docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Data, Materialization et Store
 
@@ -19,7 +19,7 @@ Il définit les frontières durables de données KSP et précise :
 - sémantique des notifications de données persistées ;
 - stabilité différente entre niveaux structurants et projections spécialisées.
 
-Cette tranche ne détaille pas encore le lifecycle complet, batching, concurrence ou supervision des workers/jobs. Ces sujets sont déplacés vers `pre.007`.
+Le lifecycle complet, batching, concurrence, backlog et reprise des workers/jobs sont détaillés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
 
 ## Nomenclature des niveaux durables
 
@@ -555,7 +555,7 @@ Il ne doit pas être nécessaire de refaire toute la chaîne lorsqu'un niveau in
 
 Les replays sont des **jobs bornés**, pas des modes cachés des workers live.
 
-Les noms exacts des futurs jobs de replay sont reportés à `pre.007`.
+Les jobs de replay retenus sont `ksp-job-replay-core`, `ksp-job-replay-generic-materialization` et `ksp-job-replay-domain-projection`.
 
 # Notifications de données persistées
 
@@ -649,7 +649,7 @@ broker externe
 
 `ksp-store-lib` peut fournir PostgreSQL LISTEN/NOTIFY comme mécanisme de référence si cela répond au premier besoin.
 
-Le choix détaillé des mécanismes, reprise, batching et multi-process est reporté à `pre.007`.
+Le mécanisme initial de référence et la reprise opérationnelle sont détaillés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
 
 # Acquisition live et backfill
 
@@ -690,7 +690,7 @@ Chaque worker :
 - écrit seulement le niveau durable dont il est propriétaire ;
 - ne transforme pas silencieusement plusieurs frontières en une étape monolithique.
 
-Le détail lifecycle, concurrence, batching, cursors, checkpoints et hot reconfiguration est reporté à `pre.007`.
+Le lifecycle, la concurrence, les cursors/checkpoints et la hot reconfiguration sont détaillés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
 
 # Projections de trading et autres domaines
 
@@ -722,11 +722,12 @@ La première implémentation Store devra encore fixer :
 - conversion u64/slot/PostgreSQL ;
 - stratégie des migrations initiales.
 
-`pre.007` doit préciser :
+Les sujets opérationnels worker/job ont été précisés dans `009-ACQUISITION_WORKERS_AND_JOBS.md`.
 
-- lifecycle des quatre workers ;
-- jobs de replay ;
-- checkpoint/backlog ;
-- batching/concurrence ;
-- mécanisme de notification de référence ;
-- processus/IPC selon les managers retenus.
+Restent à définir à l'implémentation :
+
+- schémas SQL et contraintes exactes ;
+- format concret des DTO D1/D2/D3/D4 ;
+- claim/lease PostgreSQL ;
+- contexte des projectors stateful ;
+- mécanisme IPC des managers de services autonomes.

docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Acquisition, workers, jobs et pipelines spécialisés
 
@@ -23,7 +23,7 @@ Il transforme les frontières durables D1–D4 en modèle opérationnel et défi
 - hot reconfiguration du raw retriever ;
 - batching, backpressure et métriques opérationnelles minimales.
 
-Les apps, managers desktop, IPC et orchestrateur global sont reportés à `pre.008`.
+Les apps spécialisées, services autonomes, control plane, scenarios et frontière IPC sont détaillés dans `010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`. Une application globale reste future ; un orchestrateur commun n'est pas une crate retenue actuellement.
 
 # Principe : une frontière de processing, une logique réutilisable
 
@@ -901,4 +901,4 @@ Les premières implémentations doivent encore fixer :
 - politique précise de pause/resume des jobs ;
 - métriques/export telemetry au-delà des logs et health.
 
-`pre.008` doit maintenant se concentrer sur apps, managers, scenarios, processus/IPC et orchestration globale.
+La couche supérieure est désormais cadrée dans `010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`. Le mécanisme IPC exact et l'éventuel orchestrateur restent à décider uniquement sur besoin concret.