v0.3.9-pre.008

crates/ksp-worker-api/README.md

@@ -1,9 +1,9 @@
 <!-- file: crates/ksp-worker-api/README.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # ksp-worker-api
 
-`ksp-worker-api` fournit les contrats passifs et runtime-neutral communs aux services continus KSP.
+`ksp-worker-api` fournit les contrats passifs et runtime-neutral communs aux services continus KSP. Elle décrit un Worker observable ; elle n'est ni un runtime de Worker ni une API métier d'acquisition.
 
 La crate possède l'identité logique d'un Worker, son lifecycle continu, une classification minimale de health/activity, l'intention de stop coopératif et un contrat latest-value fixe pour l'observation. Elle ne possède aucun runtime concret, aucune politique de restart, aucun Job, aucun Transport, aucun Store et aucun contrat Solana.
 
@@ -45,9 +45,11 @@ Les mises à jour intermédiaires peuvent être coalescées : le contrat porte s
 
 `WorkerStopToken` représente uniquement une intention coopérative partagée. Il ne tue pas une tâche, ne ferme pas un socket et ne décide pas du résultat terminal. Le runtime concret observe cette intention puis pilote `WorkerLifecycle` selon sa politique de shutdown.
 
-## Restart et contrôle
+## Contrôle runtime et restart
 
-La crate ne possède aucun `restart()`, scheduler, retry/backoff, process manager ou handle runtime générique. Un lifecycle/source terminal n'est jamais réanimé ni rebinding vers une nouvelle exécution. La recréation et la supervision appartiennent au caller ou à une couche de contrôle supérieure.
+La crate ne possède aucune opération runtime générique `start()`, `stop()`, `restart()`, aucun scheduler, retry/backoff, process manager ou handle d'exécution. `WorkerLifecycle` expose uniquement les transitions d'état détenues par le producer concret ; `WorkerStopToken` exprime uniquement une intention coopérative.
+
+Un lifecycle/source terminal n'est jamais réanimé ni rebinding vers une nouvelle exécution. Démarrage, arrêt effectif, drain, join, recréation et supervision appartiennent au Worker concret, au caller ou à une couche de contrôle supérieure.
 
 ## Firewall
 

crates/ksp-worker-api/USAGE.md

@@ -1,5 +1,5 @@
 <!-- file: crates/ksp-worker-api/USAGE.md -->
-<!-- version: 1 -->
+<!-- version: 2 -->
 
 # Utilisation de ksp-worker-api
 
@@ -25,8 +25,10 @@ fn worker_identity() -> ksp_worker_api::Result<(ksp_worker_api::WorkerId, ksp_wo
 
 ## Piloter un lifecycle passif
 
+Le lifecycle ne démarre aucun runtime. L'exemple suivant représente uniquement les transitions publiées par un producer concret lorsqu'il entre en exécution :
+
 ```rust
-fn start_worker(id: ksp_worker_api::WorkerId, kind: ksp_worker_api::WorkerKindCode) -> ksp_worker_api::Result<ksp_worker_api::WorkerLifecycle> {
+fn running_lifecycle(id: ksp_worker_api::WorkerId, kind: ksp_worker_api::WorkerKindCode) -> ksp_worker_api::Result<ksp_worker_api::WorkerLifecycle> {
     let mut lifecycle = ksp_worker_api::WorkerLifecycle::new(id, kind);
     if let std::result::Result::Err(error) = lifecycle.start() {
         return std::result::Result::Err(error);
@@ -95,6 +97,12 @@ Le premier appel qui change l'intention retourne `true`. Les demandes suivantes
 
 Le token n'est pas une primitive de kill et ne garantit aucun délai de shutdown. Timeout, drain, join et retry appartiennent au runtime/caller.
 
+## Démarrer et arrêter un Worker concret
+
+`ksp-worker-api` n'expose volontairement aucune commande runtime universelle. Une crate concrète peut fournir une surface `start`/`stop` adaptée à son domaine, mais elle utilise les contrats communs pour publier son identité, ses transitions, son état courant et l'intention de stop.
+
+Un Worker concret ne doit donc pas transformer `WorkerLifecycle` en handle d'exécution ni ajouter des paramètres métier au contrat générique. Les paramètres/configurations propres à une famille de Workers restent dans cette famille ou dans sa couche de composition.
+
 ## Observer un snapshot latest-value
 
 Un consumer portable peut travailler directement avec le trait object-safe :