# Normalizer v2 Spec

## Назначение

`Normalizer v2` переводит слой нормализации с single-intent модели на decomposition-first:

`raw message -> fragments + scope + flags -> deterministic routing in code`

LLM в v2 не выдает финальное route-решение как источник истины.
LLM возвращает структурированную семантику, а маршрут выбирается правилами в коде.

## Вход

- Сырое сообщение пользователя (в т.ч. длинное, multi-intent, шумное).

## Выход

- JSON по схеме `normalized_query_v2`.
- Ключевые части:
  - `message_in_scope`, `scope_confidence`
  - `fragments[]`
  - `discarded_fragments[]`
  - `global_notes`

## Fragment Contract

Каждый фрагмент содержит:
- domain gating (`domain_relevance`, `business_scope`);
- semantic hints (`entity_hints`, `account_hints`, `document_hints`, `register_hints`);
- `time_scope`;
- route-critical flags;
- `candidate_labels` (multi-label, без жесткого single-intent);
- `confidence`.

## Deterministic Routing

Код применяет правила к `flags`:

1. `asks_for_exact_object_trace=true` -> `live_mcp_drilldown`
2. `asks_for_ranking_or_top=true` или `asks_for_period_summary=true` -> `batch_refresh_then_store`
3. `has_multi_entity_scope=true` и `asks_for_chain_explanation=true` -> `hybrid_store_plus_live`
4. `asks_for_rule_check=true` и нет causal-chain -> `store_feature_risk`
5. `asks_for_anomaly_scan=true` без heavy/causal -> `store_feature_risk`
6. fragment `out_of_scope` -> `no_route`
7. остальное in-scope -> `store_canonical`

## Совместимость

- `v1` и `v2` поддерживаются параллельно.
- Выбор схемы:
  - `promptVersion=normalizer_v2` (или `schemaVersion=v2`) -> `normalized_query_v2`
  - иначе -> `normalized_query_v1`

## UI-диагностика v2

Добавлены диагностические представления:
- Fragment View
- Scope View
- Flags View
- Route Simulation

## Ограничения этапа

- Полноценный quality-eval v2 отдельно планируется (см. `reports/v2_pilot_eval_plan.md`).
- Старый eval runner метрик `intent/route` ориентирован на v1 и не является основным приемочным контуром для v2.