docs/CLASSIFICATION_GRAPH_NETWORK.md

# GraphShieldMistral Classification Network

GraphShieldMistral converts the Shieldstral hierarchy and classification JSON into a query-aware NetworkX graph.

## Scenario-state contract

A scenario is assigned exactly one presentation state:

| State | Meaning |
|---|---|
| `SAFE` | No raw or descendant-supported unsafe-policy match was observed. |
| `UNRESOLVED` | Broad/raw unsafe matches exist, but no descendant leaf was validated. |
| `CLASSIFIED` | Exactly one descendant leaf was validated. |
| `AMBIGUOUS` | Multiple descendant leaves were validated; the highest-scoring leaf is primary. |

`UNRESOLVED` is intentionally distinct from `SAFE`. For example, strong Cybercrime and System Attacks matches without a Malware leaf are represented as a broad-match/leaf-miss result, not a safe result.

## Scenario panel

The browser panel displays:

- exact submitted document and capture source;
- classification instruction;
- classification state and explanation;
- primary class, score and policy query;
- validated hierarchy path;
- all validated leaves;
- secondary matched leaves for ambiguous results;
- raw unmatched/orphan branches;
- raw and reconciled unsafe flags;
- hierarchy consistency and ambiguity state;
- expected diagnostic category when supplied.

## Clusters

Structural clusters always follow the published superclass hierarchy. Classified and ambiguous scenarios are grouped by the superclass of the primary validated leaf. Safe and unresolved results use explicit `STATUS_SAFE` and `STATUS_UNRESOLVED` clusters. Empirical NetworkX communities are derived only from validated leaf co-occurrence and remain separate from the structural taxonomy.

## Exports

- `classification-network.html`
- `classification-network.svg`
- `classification-network.graphml`
- `classification-network.json`
- `classification-clusters.json`
- optional co-classification GraphML and JSON

The cluster summary includes `classification_status_counts`, detailed validated leaves, secondary leaves, raw unmatched branches, expected-category outcomes and hierarchy-consistency fields.
## Diagnostic contract semantics

Controlled scenarios may specify an intended primary category, a required category-presence rule, and a set of allowed states. This is more precise than requiring every positive example to be `CLASSIFIED`:

- `CLASSIFIED,AMBIGUOUS` means the intended primary category must be correct, while secondary leaves remain visible rather than being suppressed;
- `UNRESOLVED` with an `absent` leaf requirement records a deliberate broad-match/leaf-miss probe;
- an ambiguity probe can require `AMBIGUOUS` and a specific primary category.

`--strict-expectations` verifies this diagnostic contract. It does not reinterpret model output or remove secondary classifications.