SYNOMAP V2 — Schéma d'architecture Python (projection)
======================================================

Objectif
--------
Ce document donne une vue d'ensemble de l'architecture Python envisagée
pour Synomap V2, afin de :
- séparer clairement la logique métier du Shell,
- disposer d'un "cerveau" Python aligné sur la SPEC V2,
- préparer la migration progressive sans tout casser d'un coup.

Vue globale (ASCII)
-------------------

        +-------------------+
        |   Shell Scripts   |
        | (cron / glue / IO)|
        +---------+---------+
                  |
                  | 1) collecte brute (qB, FS, mapping)
                  v
        +--------------------------+
        |   synomap_collect.py    |
        |  - interroge qB, FS     |
        |  - consolide en JSONL   |
        +-----------+-------------+
                    |
                    | 2) analyse / classification (SPEC V2)
                    v
        +--------------------------+
        |    synomap_check.py     |
        |  - applique modèle ABC  |
        |  - applique blocs H/D/E |
        |    G/HASH + issues      |
        |  - produit STATE +      |
        |    ISSUES + STATUS      |
        +-----------+-------------+
                    |
                    | 3) génération plan d'actions
                    v
        +--------------------------+
        |    synomap_plan.py      |
        |  - lit l'état (check)   |
        |  - applique règles V2   |
        |  - produit ACTION_PLAN  |
        +-----------+-------------+
                    |
                    | 4) exécution concrète
                    v
        +--------------------------+
        |    synomap_exec.py      |
        |  - applique ACTION_PLAN |
        |  - appelle qB / FS      |
        |  - journalise résultats |
        +--------------------------+

Rôles détaillés
---------------

1) synomap_collect.py
   - Entrées :
     - configuration (paths, accès qB, mapping_entries, etc.)
   - Sorties :
     - fichier JSONL "raw_state" : perception brute (torrents, fichiers, chemins, tags, etc.)
   - Contraintes :
     - pas de logique métier complexe,
     - doit juste être fiable, répétable, traçable.

2) synomap_check.py
   - Entrée :
     - JSONL "raw_state" produit par collect.
   - Sortie :
     - JSONL "checked_state" :
       - état ABC,
       - blocs H/D/E/G/HASH,
       - issues,
       - overall_status.
   - Logique :
     - implémente strictement la SPEC V2 (A1..A4, Issues V2, DOC_OV1 V2, JSONL V2).
   - Règle d'or :
     - aucune action sur le monde (qB / FS) → uniquement du diagnostic.

3) synomap_plan.py
   - Entrée :
     - JSONL "checked_state".
   - Sortie :
     - JSONL "action_plan" :
       - liste d'actions unitaires (MOVE, TAG, REMOVE, RECHECK, etc.),
       - chacune avec :
         - cible,
         - préconditions,
         - sévérité,
         - lien avec issue / GAP.
   - Rôle :
     - transformer l'état diagnostiqué en séquence d'actions possibles / recommandées,
     - respecter les priorités / invariants définis dans la SPEC V2.

4) synomap_exec.py
   - Entrée :
     - JSONL "action_plan".
   - Sortie :
     - logs d'exécution,
     - éventuellement JSONL "execution_report".
   - Rôle :
     - exécuter les actions sur qB / FS (via API / commandes),
     - gérer les erreurs locales,
     - ne pas réinventer la logique métier (elle doit rester dans plan/check).

Interaction avec le Shell
-------------------------
À terme, les scripts Shell actuels évolueront vers des "orchestrateurs" :

- daily_qbittorrent_update_* :
  - appellera synomap_collect.py
  - puis synomap_check.py (optionnel en routine)

- synomap_chain_preview_* :
  - appellera synomap_collect.py
  - puis synomap_check.py
  - puis synomap_plan.py en mode "preview"

- synomap_apply_from_plan.sh :
  - appellera synomap_exec.py sur un ACTION_PLAN déjà produit.

Principes clés
--------------
- Python = logique métier et cohérence, Shell = colle et scheduling.
- Tous les échanges entre Python et Shell passent par des fichiers JSONL
  et/ou des flux stdout / stdin bien définis.
- La SPEC V2 est la source de vérité :
  - pour les états,
  - pour les structures JSON,
  - pour les types d'actions,
  - pour la gestion des erreurs et priorités.

Ce document ne fige pas encore les signatures exactes des CLIs, mais
donne le squelette pour que la SPEC V2 puisse décrire proprement :
- les champs de chaque JSON,
- les invariants,
- les codes d'actions,
- les transitions autorisées.