feat(update): scaffold MAJ silencieuse + canary par machine (DETTE-022, gated OFF, swap encore stub)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

agent_v0/server_v1/api_stream.py

@@ -7848,6 +7848,9 @@ async def lea_screen_analyze(payload: _Phase25ScreenRequest, request: Request):
 # client + Lea.bat).
 # =========================================================================
 from .update_check import decide_update as _decide_update  # noqa: E402
+from .update_policy import (  # noqa: E402
+    resolve_target_version_from_env as _resolve_target_version_from_env,
+)
 
 
 def _auto_update_server_enabled() -> bool:
@@ -7857,14 +7860,25 @@ def _auto_update_server_enabled() -> bool:
     )
 
 
-def _latest_agent_version() -> str:
-    """Dernière version d'agent disponible côté serveur.
+def _latest_agent_version(machine_id: Optional[str] = None) -> str:
+    """Version d'agent cible POUR CE POSTE (canary-aware, DETTE-022 v2).
 
-    Source de vérité minimale (POC) : variable d'environnement
-    RPA_AGENT_LATEST_VERSION. Permet de piloter la fleet sans rebuild. Une
-    évolution future pourra la lire d'un manifeste/DB (cf. design).
+    ⭐ SÉCURITÉ flotte ⭐ — la version servie est résolue PAR MACHINE via la
+    politique canary (`update_policy.resolve_target_version_from_env`) : un
+    poste canary (Émilie `lea-4zbgwxty`) reçoit la nouvelle version en premier ;
+    tous les autres restent sur le floor stable. Piloté 100 % par env, sans
+    rebuild :
+        RPA_AGENT_STABLE_VERSION   (défaut 1.0.1) — servi à toute la flotte.
+        RPA_AGENT_CANARY_VERSION   — servi AUX SEULS postes canary.
+        RPA_AGENT_CANARY_MACHINES  — allow-list CSV des machine_id canary.
+
+    Rétrocompat : si `RPA_AGENT_LATEST_VERSION` (ancienne var globale) est
+    positionnée, elle prime — évite toute régression d'un déploiement existant.
     """
-    return os.environ.get("RPA_AGENT_LATEST_VERSION", "1.0.1")
+    legacy = os.environ.get("RPA_AGENT_LATEST_VERSION")
+    if legacy:
+        return legacy
+    return _resolve_target_version_from_env(machine_id)
 
 
 @app.get("/api/v1/agents/update/check")
@@ -7877,6 +7891,10 @@ async def check_agent_update(
 
     Réponse : {update_available, latest_version, update_type, url}.
 
+    La version cible est résolue PAR MACHINE (canary) : voir
+    `_latest_agent_version`. Un poste hors canary ne se voit JAMAIS proposer la
+    version canary (blast radius borné à la liste canary).
+
     GATED : si RPA_AUTO_UPDATE_SERVER_ENABLED n'est pas positionné → 503
     (aucun effet sur le pipeline existant — anti-régression). Auth Bearer
     requise (dépendance globale `_verify_token`).
@@ -7891,7 +7909,7 @@ async def check_agent_update(
         )
     return _decide_update(
         current_version=current_version,
-        latest_version=_latest_agent_version(),
+        latest_version=_latest_agent_version(machine_id),
         update_type=update_type,
         machine_id=machine_id,
     )

agent_v0/server_v1/update_policy.py

@@ -0,0 +1,139 @@
+# agent_v0/server_v1/update_policy.py
+"""Politique de déploiement CANARY de la MAJ silencieuse Léa (DETTE-022 v2).
+
+⭐ Brique de SÉCURITÉ centrale ⭐ — 10+ postes cliniques live (Wallerstein).
+
+Une MAJ ratée peut briquer toute la flotte. La règle non négociable : on ne
+pousse JAMAIS une nouvelle version sur tous les postes d'un coup. On la déploie
+d'abord sur UN poste (canary = Émilie `lea-4zbgwxty`), on vérifie, puis on
+élargit. Ce module résout, PAR MACHINE, la version cible :
+
+  - poste dans la liste canary  → `canary_version` (la nouvelle) ;
+  - tous les autres postes       → `stable_version` (le floor, inchangé).
+
+Piloté 100 % par variables d'environnement (config serveur, sans rebuild) :
+  RPA_AGENT_STABLE_VERSION   — version servie à toute la flotte (défaut floor).
+  RPA_AGENT_CANARY_VERSION   — version servie AUX SEULS postes canary (optionnel).
+  RPA_AGENT_CANARY_MACHINES  — allow-list CSV des machine_id canary.
+
+Promotion = quand le canary est validé, on met RPA_AGENT_STABLE_VERSION à la
+version canary (toute la flotte suit) et on vide RPA_AGENT_CANARY_MACHINES.
+Rollback canary = on remet RPA_AGENT_CANARY_VERSION à l'ancienne / on vide la
+liste : le prochain check ne proposera plus la MAJ (le swap réel côté client
+reste réservé révision humaine — cf. updater.py).
+
+Module PUR (aucun import FastAPI, aucune IO) → importable et testable seul
+(DETTE-013). Le branchement HTTP vit dans api_stream.py.
+
+Branche feat/push-log-dgx.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional, Set
+
+# Réutilise le comparateur semver de la décision (même module serveur, pas de
+# duplication) : "1.0.2" < "1.0.10" correctement, tolérant aux formats invalides.
+try:  # import relatif quand chargé comme package
+    from .update_check import is_newer
+except Exception:  # chargé par chemin (tests importlib) : import du voisin
+    import importlib.util as _ilu
+    from pathlib import Path as _Path
+
+    _uc_path = _Path(__file__).resolve().parent / "update_check.py"
+    _spec = _ilu.spec_from_file_location("_rpa_update_check_for_policy", _uc_path)
+    _uc = _ilu.module_from_spec(_spec)
+    _spec.loader.exec_module(_uc)
+    is_newer = _uc.is_newer
+
+
+# Séparateurs tolérés dans l'allow-list canary (CSV, espaces, point-virgule).
+_CANARY_SEPARATORS = (",", ";")
+
+
+def parse_canary_machines(raw: Optional[str]) -> Set[str]:
+    """Parse l'allow-list canary en un ensemble de machine_id.
+
+    Tolérant : virgule / point-virgule / espace comme séparateurs, entrées
+    vides ignorées. `None` ou chaîne vide → ensemble vide (aucun canary).
+    """
+    if not raw or not isinstance(raw, str):
+        return set()
+    normalized = raw
+    for sep in _CANARY_SEPARATORS:
+        normalized = normalized.replace(sep, " ")
+    return {tok for tok in (t.strip() for t in normalized.split()) if tok}
+
+
+def resolve_target_version(
+    machine_id: Optional[str],
+    stable_version: str,
+    canary_version: Optional[str],
+    canary_machines: Set[str],
+) -> str:
+    """Résout la version cible POUR CE POSTE (cœur canary — sécurité).
+
+    Règles (toutes prudentes par défaut) :
+      1. Poste HORS liste canary → `stable_version` (jamais la nouvelle).
+      2. machine_id absent / liste vide / pas de canary_version → `stable_version`.
+      3. Poste DANS la liste canary ET `canary_version` fournie ET STRICTEMENT
+         plus récente que stable → `canary_version`.
+      4. Garde-fou : si `canary_version` <= `stable_version` (config douteuse,
+         ex. downgrade), on sert quand même `stable_version` (jamais de recul).
+
+    Ne lève jamais. Une version illisible retombe naturellement sur le stable
+    via le comparateur semver tolérant.
+    """
+    # Cas 1/2 : hors canary → stable.
+    if not machine_id or machine_id not in canary_machines:
+        return stable_version
+    if not canary_version:
+        return stable_version
+
+    # Cas 4 : garde-fou anti-recul — le canary doit être STRICTEMENT plus récent.
+    if not is_newer(canary_version, stable_version):
+        return stable_version
+
+    # Cas 3 : poste canary → nouvelle version.
+    return canary_version
+
+
+# ---------------------------------------------------------------------------
+# Lecture de la politique depuis l'environnement (pilotage sans rebuild).
+# ---------------------------------------------------------------------------
+
+# Défaut historique aligné sur AGENT_VERSION client (config.py) et sur le
+# fallback de _latest_agent_version().
+_DEFAULT_STABLE_VERSION = "1.0.1"
+
+
+def stable_version_from_env() -> str:
+    """Version servie à toute la flotte (floor). Défaut = 1.0.1."""
+    return os.environ.get("RPA_AGENT_STABLE_VERSION", _DEFAULT_STABLE_VERSION)
+
+
+def canary_version_from_env() -> Optional[str]:
+    """Version canary (nouvelle), servie aux seuls postes canary. Optionnel."""
+    val = os.environ.get("RPA_AGENT_CANARY_VERSION", "").strip()
+    return val or None
+
+
+def canary_machines_from_env() -> Set[str]:
+    """Allow-list canary (machine_id) depuis RPA_AGENT_CANARY_MACHINES."""
+    return parse_canary_machines(os.environ.get("RPA_AGENT_CANARY_MACHINES", ""))
+
+
+def resolve_target_version_from_env(machine_id: Optional[str]) -> str:
+    """Raccourci : résout la version cible pour `machine_id` d'après l'env.
+
+    C'est le point d'entrée que l'endpoint serveur appelle. Il isole toute la
+    lecture d'environnement ici (testable en injectant les paramètres via
+    `resolve_target_version`).
+    """
+    return resolve_target_version(
+        machine_id=machine_id,
+        stable_version=stable_version_from_env(),
+        canary_version=canary_version_from_env(),
+        canary_machines=canary_machines_from_env(),
+    )