Synomap – DOC_OV1 – Spécification lisible de overall_status (v1)
===============================================================

1. Objet
--------
Ce document décrit de manière lisible mais technique le calcul du champ
overall_status dans la sortie du Checker Synomap. Il s’appuie sur :
- les blocs de statut (H, D, E, G, HASH, ABC),
- la table des issues (codes, severities, flags blocked_by_code),
- la hiérarchie de niveaux : BLOCKED > ERROR > WARN > OK.

Le but est d’offrir une référence pour :
- les développeurs qui implémentent le Checker,
- les intégrateurs API / UI qui consomment la sortie du Checker.


2. Entrées du calcul
--------------------

2.1. États des blocs
Pour chaque torrent, le Checker calcule un objet state, incluant au minimum :

- state.block_h.h_state        (H0 / H1 / H2 / H3)
- state.block_d.qb_status      (SAFE / UNSAFE)
- state.block_d.save_path_ok   (bool)
- state.block_d.tags_state     (CONSISTENT / MISMATCH / UNKNOWN)
- state.block_e.mapping_status (OK / MISSING / AMBIGUOUS / INCONSISTENT)
- state.block_g.fs_src         (OK / MISSING / PARTIAL / UNREADABLE)
- state.block_g.fs_dst         (OK / MISSING / PARTIAL / UNREADABLE)
- state.block_g.mirror         (COMPLETE / INCOMPLETE / UNKNOWN)
- state.block_hash.hf_state    (HF0 / HF1 / HF2 / HF3 / HF4)
- state.abc_state              (A / B / C / NONE)

Les spécificités de chaque bloc (ABC / H / D / E / G / HASH) sont définies dans
les documents précédents de la Loop Spec.


2.2. Issues
Le Checker produit, pour chaque torrent, un tableau diagnostic.issues[] où
chaque élément contient au minimum :
- code           (string stable, ex : SRC_MISSING),
- block          (H / D / E / G / HASH / ABC),
- severity       (INFO / WARN / ERROR),
- blocked_by_code (bool).

La table de référence “Synomap – Issues Table v1 (Consolidated)” définit pour
chaque code :
- son bloc,
- sa severity,
- si blocked_by_code est true ou false.


3. Conditions de blocage par blocs
----------------------------------

3.1. H_blocked(state)
H_blocked(state) est vrai si :
    h_state ≠ H0

3.2. D_blocked(state)
D_blocked(state) est vrai si :
    qb_status = UNSAFE
    OU (save_path_ok = false ET abc_state ∈ {B, C})
    OU (tags_state = MISMATCH_CRITIQUE, via l’issue associée)

3.3. E_blocked(state)
E_blocked(state) est vrai si :
    mapping_status ≠ OK
soit MISSING, AMBIGUOUS ou INCONSISTENT.

3.4. G_blocked(state)
G_blocked(state) est vrai si :
    fs_src ≠ OK
    OU (abc_state ∈ {B, C} ET fs_dst ≠ OK)
    OU (abc_state ∈ {B, C} ET mirror = INCOMPLETE)
    OU (abc_state = C ET mirror = UNKNOWN)

3.5. HASH_blocked(state)
HASH_blocked(state) est vrai si :
    hf_state = HF4


3.6. blocked_by_blocks(state)
On regroupe :
    blocked_by_blocks(state) =
        H_blocked(state)   OU
        D_blocked(state)   OU
        E_blocked(state)   OU
        G_blocked(state)   OU
        HASH_blocked(state)


4. Conditions de blocage par issues
-----------------------------------

4.1. blocked_by_issues(issues)
On définit :
    blocked_by_issues(issues) =
        existe issue telle que issue.blocked_by_code = true

Les codes concernés sont définis dans la table des issues v1, par blocs :
- Bloc H      : SRC_PARTIAL, SRC_MISSING, SRC_UNREADABLE,
- Bloc D      : QB_STATUS_UNSAFE, QB_SAVEPATH_INCOHERENT_BC,
                QB_TAGS_MISMATCH_CRITIQUE,
- Bloc E      : MAPPING_MISSING, MAPPING_AMBIGUOUS, MAPPING_INCONSISTENT,
- Bloc G      : FS_SRC_*, FS_DST_*_BC, MIRROR_INCOMPLETE_BC, MIRROR_UNKNOWN_C,
- Bloc HASH   : HASH_COLLISION_SEVERE.

Cette double voie (blocs + issues) permet :
- un blocage même si une issue n’est pas créée (fail-safe),
- un blocage même si un bloc est mal interprété mais qu’un code métier est présent.


5. Algorithme de calcul de overall_status
-----------------------------------------

5.1. Hiérarchie des niveaux
La hiérarchie est : BLOCKED > ERROR > WARN > OK.
Le calcul est fait en quatre étapes séquentielles.

5.2. Pseudo-code
Pour un torrent donné, on applique :

    overall_status = "OK"

    // 1) Niveau BLOCKED (priorité blocs)
    if blocked_by_blocks(state):
        overall_status = "BLOCKED"

    // 2) Niveau BLOCKED (issues bloquantes)
    elif blocked_by_issues(issues):
        overall_status = "BLOCKED"

    // 3) Niveau ERROR
    elif any(issue.severity == "ERROR" for issue in issues):
        overall_status = "ERROR"

    // 4) Niveau WARN
    elif any(issue.severity == "WARN" for issue in issues):
        overall_status = "WARN"

    // 5) Sinon
    else:
        overall_status = "OK"


6. Propriétés importantes
-------------------------

6.1. Déterminisme
À state.* et issues[] identiques, overall_status est toujours identique.
Aucun facteur externe ne doit influencer ce calcul.

6.2. Fail-safe (OVA2a)
Même si l’implémentation oublie de créer une issue pour un bloc bloquant,
blocked_by_blocks(state) garantit que le torrent sera tout de même marqué
BLOCKED.

6.3. Extensibilité
La table des issues peut être étendue (nouveaux codes, nouveaux WARN/ERROR)
sans changer la structure générale du calcul :
- les nouveaux codes respecteront simplement la même logique :
  - blocked_by_code = true → potentiel BLOCKED,
  - severity = ERROR/WARN → impact sur ERROR/WARN.


7. Intégration avec la sortie du Checker
----------------------------------------
Dans la structure de sortie du Checker, overall_status vit dans :

    diagnostic.overall_status = "OK"|"WARN"|"ERROR"|"BLOCKED"

aux côtés de :
- diagnostic.issues[],
- diagnostic.auto_fix_candidates[] (optionnel).

Les blocs et hash_state vivent dans la partie state.*
(cf. “Synomap – Loop Spec v1 – Checker Output Format (v7)”).


8. Références croisées
----------------------
Ce document DOC_OV1 doit être utilisé conjointement avec :
- “Synomap – Loop Spec v1 – Bloc ABC (flux normal, seedtime-only)”,
- “Synomap – Loop Spec v1 – Checker Output Format (v7)”,
- “Synomap – Issues Table v1 (Consolidated)”,
- les spécifications détaillées des blocs H, D, E, G et HASH.