fix(prod-hotfix)!: serve_cmd referenced deleted picarones.web package

Bug en prod (HuggingFace Space, 2026-05-10) : ``picarones serve``
plantait au démarrage uvicorn avec :

ModuleNotFoundError: No module named 'picarones.web'

Cause racine
------------
``picarones/interfaces/cli/_serve.py:70`` passait à ``uvicorn.run``
la string ``"picarones.web.app:app"`` qui pointait vers le paquet
legacy ``picarones/web/`` — supprimé au sprint H.4 (mai 2026) lors
du retrait complet du legacy. Le chemin canonique v2.0 est
``picarones.interfaces.web.app:app``.

Pourquoi le bug n'a pas été pris au CI
--------------------------------------
Aucun test n'exerçait la string passée à uvicorn. Les tests web
existants instancient ``app`` directement via ``TestClient(app)``
(sans uvicorn), donc l'import ``picarones.web.app:app`` n'était
jamais testé même si le code de production en dépendait pour
démarrer.

Fix
---
1. ``_serve.py:70`` : ``picarones.web.app:app`` →
``picarones.interfaces.web.app:app``.
2. Nettoyage des docstrings obsolètes (5 fichiers) qui référençaient
encore le paquet supprimé — induisaient en erreur tout
utilisateur qui copie-collait l'exemple uvicorn.
3. ``tests/interfaces/cli/test_s9_serve_module_path.py`` (5 tests) :
garde-fou anti-régression qui parse ``_serve.py`` par AST,
extrait la string ``module:attr``, et vérifie :
- format valide,
- module importable réellement,
- attribut existe sur le module,
- attribut est bien une instance ``FastAPI``,
- chemin canonique v2.0 utilisé (pas ``picarones.web.*``).

Vérification manuelle : ``import_from_string('picarones.interfaces.web.app:app')``
retourne maintenant un ``FastAPI`` avec 35 routes.

Régression : 4548 passed, 0 failed, ruff clean.

picarones/app/services/path_security.py

@@ -1,8 +1,8 @@
 """``WorkspaceManager`` + helpers de validation de chemin — Sprint A14-S19.
 
 Foyer définitif des helpers ``validated_path``, ``safe_report_name``,
-``validated_prompt_filename`` créés au S1.  Les anciens callers
-(``picarones.web.security``) ré-importent depuis ce module.
+``validated_prompt_filename`` créés au S1.  Les callers web
+(``picarones.interfaces.web.security``) ré-importent depuis ce module.
 
 Pourquoi ici
 ------------

picarones/interfaces/cli/_serve.py

@@ -67,7 +67,7 @@ def serve_cmd(host: str, port: int, reload: bool, verbose: bool) -> None:
 
     log_level = "debug" if verbose else "info"
     uvicorn.run(
-        "picarones.web.app:app",
+        "picarones.interfaces.web.app:app",
         host=host,
         port=port,
         reload=reload,

picarones/interfaces/web/app.py

@@ -6,21 +6,21 @@ Lance avec :
 
     picarones serve [--port 8000] [--host 127.0.0.1]
     # ou directement :
-    uvicorn picarones.web.app:app --reload --port 8000
+    uvicorn picarones.interfaces.web.app:app --reload --port 8000
 
 L'application est intentionnellement minimaliste : elle se contente
 d'instancier ``FastAPI``, de monter le middleware de sécurité (CSP,
 en-têtes durcis), de servir les fichiers statiques, puis d'inclure
-les 11 routers thématiques de :mod:`picarones.web.routers`. Toute la
-logique métier vit dans les sous-modules :
-
-- :mod:`picarones.web.state` — singletons et helpers transverses
-- :mod:`picarones.web.models` — Pydantic schemas
-- :mod:`picarones.web.corpus_utils` — parsing XML, analyse corpus
-- :mod:`picarones.web.engine_utils` — détection moteurs, capacités
-- :mod:`picarones.web.benchmark_utils` — workers threadés
-- :mod:`picarones.web.config_utils` — validation config utilisateur
-- :mod:`picarones.web.routers.*` — 11 ``APIRouter`` thématiques
+les 11 routers thématiques de :mod:`picarones.interfaces.web.routers`.
+Toute la logique métier vit dans les sous-modules :
+
+- :mod:`picarones.interfaces.web.state` — singletons et helpers transverses
+- :mod:`picarones.interfaces.web.models` — Pydantic schemas
+- :mod:`picarones.interfaces.web.corpus_utils` — parsing XML, analyse corpus
+- :mod:`picarones.interfaces.web.engine_utils` — détection moteurs, capacités
+- :mod:`picarones.interfaces.web.benchmark_utils` — workers threadés
+- :mod:`picarones.interfaces.web.config_utils` — validation config utilisateur
+- :mod:`picarones.interfaces.web.routers.*` — 11 ``APIRouter`` thématiques
 """
 
 from __future__ import annotations

picarones/interfaces/web/jobs.py

@@ -1,7 +1,7 @@
 """Persistance SQLite des jobs de benchmark (Sprint 26).
 
 Avant le Sprint 26, l'état des benchmarks vivait uniquement en mémoire dans
-``picarones.web.app._JOBS``. Trois conséquences :
+``picarones.interfaces.web.app._JOBS``. Trois conséquences :
 
 1. Un redémarrage du worker uvicorn (OOM, déploiement, ``kill -HUP``)
    perdait l'état de tous les benchmarks en cours et un client SSE qui se

picarones/interfaces/web/maintenance.py

@@ -2,7 +2,7 @@
 
 Sprint A11 (item M-8 du plan de remédiation institutionnelle).
 
-Démarrée par le ``lifespan`` de ``picarones.web.app``, cette tâche
+Démarrée par le ``lifespan`` de ``picarones.interfaces.web.app``, cette tâche
 asyncio scanne le dossier ``uploads/`` toutes les ``interval_seconds``
 et supprime tout sous-dossier dont :
 

picarones/interfaces/web/observability.py

@@ -60,7 +60,7 @@ class JsonLogFormatter(logging.Formatter):
     .. code-block:: json
 
         {"timestamp": "2026-05-09T12:00:00.123Z", "level": "INFO",
-         "logger": "picarones.web.app", "message": "...",
+         "logger": "picarones.interfaces.web.app", "message": "...",
          "request_id": "abc123def456"}
 
     Champs additionnels : ``exc_type`` + ``exc_message`` aplatis si

tests/interfaces/cli/test_s9_serve_module_path.py

@@ -0,0 +1,130 @@
+"""Sprint S9 — garde-fou anti-régression pour la commande ``serve``.
+
+Bug observé en prod (HuggingFace Space, 2026-05-10) :
+``picarones serve`` plantait avec ``ModuleNotFoundError: No module
+named 'picarones.web'`` parce que ``_serve.py:70`` passait
+``"picarones.web.app:app"`` à ``uvicorn.run()``.  Le paquet
+``picarones.web/`` a été supprimé au sprint H.4 (mai 2026) lors
+du retrait complet du legacy ; la string passée à uvicorn n'a
+pas été migrée car aucun test ne l'exerçait.
+
+Ce fichier verrouille deux contrats :
+
+1. La string passée à ``uvicorn.run`` dans ``serve_cmd`` doit
+   référencer un module **réellement importable** au format
+   ``module.path:attribute``.
+2. Le module et l'attribut ``app`` (instance FastAPI) doivent
+   tous deux exister.
+
+Le test n'exécute pas uvicorn — il extrait la string par
+introspection AST du fichier source pour rester rapide et ne
+pas dépendre du serveur réel.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib
+from pathlib import Path
+
+
+def _extract_uvicorn_target() -> str:
+    """Parse ``_serve.py`` pour extraire le 1er argument de l'appel
+    à ``uvicorn.run(...)``.
+
+    Implémentation par AST plutôt que par exécution : on ne veut
+    pas démarrer un serveur ni dépendre de uvicorn pour tester
+    la validité de la string.
+    """
+    serve_path = (
+        Path(__file__).resolve().parents[3]
+        / "picarones" / "interfaces" / "cli" / "_serve.py"
+    )
+    tree = ast.parse(serve_path.read_text(encoding="utf-8"))
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            func = node.func
+            if (
+                isinstance(func, ast.Attribute)
+                and func.attr == "run"
+                and isinstance(func.value, ast.Name)
+                and func.value.id == "uvicorn"
+            ):
+                # 1er arg positionnel = target.
+                if node.args:
+                    first_arg = node.args[0]
+                    if isinstance(first_arg, ast.Constant):
+                        return str(first_arg.value)
+    raise AssertionError(
+        "Pas d'appel ``uvicorn.run(<string>, ...)`` trouvé dans "
+        "_serve.py — la commande serve a-t-elle été refactorée ?"
+    )
+
+
+class TestUvicornTargetIsImportable:
+    """Le bug ``ModuleNotFoundError: picarones.web`` observé en
+    prod ne doit jamais réapparaître : la string ``module:attr``
+    passée à uvicorn doit être valide à tout instant."""
+
+    def test_target_format_is_module_colon_attr(self) -> None:
+        target = _extract_uvicorn_target()
+        assert ":" in target, (
+            f"Target uvicorn invalide : {target!r} — "
+            "format attendu ``module.path:attr``."
+        )
+        module_path, _, attr = target.partition(":")
+        assert module_path, "Module path vide avant ':'"
+        assert attr, "Attribut vide après ':'"
+
+    def test_target_module_is_actually_importable(self) -> None:
+        """Le module nommé doit pouvoir être importé — c'est
+        exactement ce qui plantait en prod (``picarones.web``
+        n'existait plus depuis le sprint H.4)."""
+        target = _extract_uvicorn_target()
+        module_path, _, _ = target.partition(":")
+        try:
+            importlib.import_module(module_path)
+        except ImportError as exc:
+            raise AssertionError(
+                f"``uvicorn.run({target!r}, ...)`` référence un "
+                f"module non-importable : {exc}.  "
+                "Probable régression : le module a été renommé "
+                "sans mise à jour de _serve.py."
+            ) from exc
+
+    def test_target_attribute_exists_on_module(self) -> None:
+        target = _extract_uvicorn_target()
+        module_path, _, attr = target.partition(":")
+        module = importlib.import_module(module_path)
+        assert hasattr(module, attr), (
+            f"Module {module_path!r} n'a pas l'attribut {attr!r} — "
+            f"uvicorn planterait à l'instanciation."
+        )
+
+    def test_target_attribute_is_a_fastapi_app(self) -> None:
+        """Garantit que l'attribut est bien une instance FastAPI
+        (pas un module, pas une fonction) — sinon uvicorn
+        rapporterait une erreur cryptique."""
+        from fastapi import FastAPI
+
+        target = _extract_uvicorn_target()
+        module_path, _, attr = target.partition(":")
+        module = importlib.import_module(module_path)
+        app = getattr(module, attr)
+        assert isinstance(app, FastAPI), (
+            f"{target!r} → {type(app).__name__} ; FastAPI attendu."
+        )
+
+    def test_target_uses_canonical_v2_path(self) -> None:
+        """Garde-fou explicite : depuis v2.0, la web app vit dans
+        ``picarones.interfaces.web.app``, pas dans
+        ``picarones.web.app`` (paquet supprimé au sprint H.4)."""
+        target = _extract_uvicorn_target()
+        assert "picarones.interfaces.web" in target, (
+            f"Target {target!r} n'utilise pas le chemin canonique "
+            "v2.0 ``picarones.interfaces.web.app:app``."
+        )
+        assert "picarones.web." not in target, (
+            f"Target {target!r} référence le paquet legacy "
+            "``picarones.web.*`` supprimé au sprint H.4."
+        )