# Hierarchy Reconciliation

Shieldstral answers independent natural-language policies. It does not natively enforce parent-child consistency. A broad policy can therefore score positive because of lexical similarity while every leaf beneath it scores negative.

## Raw and validated views

The classifier publishes both views:

- `raw_model_matches`: unmodified thresholded model decisions.
- `hierarchy_validated_matches`: descendant-supported decisions.
- `orphan_policy_matches`: broad raw positives without a positive descendant leaf.
- `matched_leaf_categories`: all positive leaves.
- `primary_leaf`: the highest-scoring positive leaf.
- `validated_path`: primary superclass, subcategory, and leaf.
- `ambiguity`: multiple-leaf and same-parent conflict information.

## Reconciliation rule

A leaf is retained when its own policy score exceeds the threshold.

A subcategory is retained only when:

1. its own policy score exceeds the threshold; and
2. at least one child leaf exceeds the threshold.

A superclass is retained only when:

1. its own policy score exceeds the threshold; and
2. at least one descendant leaf exceeds the threshold.

This rule prevents an orphan broad match such as `Content Theft -> Media Theft` from becoming a named final classification when both `Piracy` and `Plagiarism` are negative.

## Ambiguity

Real content can violate several policies. Multiple leaf matches are therefore preserved rather than silently discarded. The output reports:

- whether classification is ambiguous;
- all matched leaves;
- same-parent sibling conflicts;
- the primary leaf selected by score.

For report-style isolated examples, a same-parent conflict should be treated as a failed discrimination case. For production moderation, it may represent genuinely multi-label content.

## Hierarchical versus exhaustive mode

Hierarchical mode evaluates all superclasses, then only children of raw-positive parents. It is efficient but can miss a leaf if its parent is a false negative.

Exhaustive mode evaluates all 90 nodes and is preferred for audits, reproducibility studies, and calibration work.