docs/reference/validation.md

# Validation

Registry-backed segment validation. Single source of truth for category metadata: `inspector/services/validation/registry.py`, hand-mirrored to `inspector/frontend/src/tabs/segments/domain/registry.ts`. Parity asserted by `inspector/frontend/src/__tests__/registry/parity.test.ts`.

Two orderings exist and are distinct:
- `accordion_order` (registry field) — UI render order in `ValidationPanel.svelte`.
- dict insertion order in `_REGISTRY` — drives `PER_SEGMENT_CATEGORIES` / `_flags_to_categories` / `category_counts` emission. **These two orders are NOT the same** (e.g. `low_confidence_v2` is insertion-pos 6 but `accordion_order=6` while `audio_bleeding`/`boundary_adj`/`repetitions` carry `accordion_order` 7/8/9 yet sit at insertion positions 8/9/7). When adding a category, set BOTH and keep registry.py ↔ registry.ts byte-aligned.

## Categories

Accordion order (registry `accordion_order`). `card_type` = FE card subcomponent dispatch.

| order | kind | severity | scope | detection | where | card_type | key module |
|---|---|---|---|---|---|---|---|
| 1 | `failed` | error | per_segment | empty `matched_ref` | server+client | generic | `classifier.py` / `detail.py` |
| 2 | `missing_verses` | error | per_verse | verse in `word_counts` not covered by any seg key | server | missingVerses | `_structural.py::_check_structural_errors` |
| 3 | `missing_words` | error | per_verse | word-index gap in verse coverage map | server | missingWords | `_missing.py::_build_missing_words` |
| 4 | `structural_errors` | error | per_chapter | `t_from>=t_to`, `w_from<1`, `w_to<w_from`, time overlap | server | error | `_structural.py` |
| 5 | `low_confidence` | warning | per_segment | `confidence < LOW_CONFIDENCE_THRESHOLD` (count); `< LOW_CONFIDENCE_DETAIL_THRESHOLD` (detail list, synthetic `low_confidence_detail`) | server | generic | `classifier.py::classify_flags` |
| 6 | `low_confidence_v2` | warning | per_segment | `segment_uid ∈ probe_failed_uids` (MFA tight-beam probe sidecar, `load_probe_v2`) | server | generic | `classifier.py` + `_build_detail_lists` |
| 7 | `audio_bleeding` | warning | per_segment | by-ayah only: `not seg_belongs_to_entry(matched_ref, entry_ref)` | server | generic | `classifier.py` |
| 8 | `boundary_adj` | warning | per_segment | persisted `is_boundary_adj` (fall-through `compute_is_boundary_adj`) | server | generic | `classifier.py::_check_boundary_adj` |
| 9 | `repetitions` | warning | per_segment | `seg.wrap_word_ranges` truthy (`has_repeated_words` alone does NOT classify) | server | generic | `classifier.py` |
| 10 | `cross_verse` | warning | per_segment | `s_ayah != e_ayah` | server | generic | `classifier.py` |
| 11 | `qalqala` | info | per_segment | persisted `qalqala_letter` non-null (fall-through `compute_qalqala_letter`) | server | generic | `classifier.py` + `segments/qalqala.py` |
| 12 | `muqattaat` | info | per_segment | `s_word==1 and (surah,s_ayah) ∈ MUQATTAAT_VERSES` | server | generic | `classifier.py` |
| 13 | `basmala_amin` | info | per_segment | per-chapter scan: first seg overlapping `1:1`, last overlapping `1:7`, + missed-Basmala augmentation gated on `len(deleted_basmala_chapters) >= MISSED_BASMALA_FLAG_MIN_DELETED` | server | generic | `detail.py::_build_detail_lists` |

Detection runs server-side in the validate pass. The client classifies snapshots/issue records for display only (`utils/validation/classified-issues.ts`), it does not own primary detection. Parent-repo `validators/validate_segments.py` (pipeline, gitignored) references the same `kind` set — accordion + post-pipeline validator must stay aligned.

Suppression: `is_suppressed_for(seg, cat)` = `is_ignored_for` (reads `seg.ignored_categories`, legacy `"_all"` marker, legacy `ignored=True` bool) OR `is_resolved_by_edit` (transient `seg._resolved_by_edit`, injected by the validate route from `build_resolved_by_edit_index`, stripped before return). `failed` is gated only on `is_ignored_for` (resolved-by-edit does not suppress errors).

## Server engine — `inspector/services/validation/`

| File | Role |
|---|---|
| `__init__.py` | Orchestrator `validate_reciter_segments(reciter)`. `ThreadPoolExecutor(4)` fan-out of the 4 independent bucket reads (`load_detailed` / `_load_resolved_idx_cached` / `load_probe_v2` / `load_seg_verses`). `canonical=None` throughout (phonemizer out of runtime). Builds `category_counts` + per-category arrays + `split_group_index`. Re-exports registry symbols + classifier API. |
| `registry.py` | `_REGISTRY` dict of frozen `IssueDefinition` rows. Derived tuples: `ALL/PER_SEGMENT/PER_VERSE/PER_CHAPTER/CAN_IGNORE/AUTO_SUPPRESS/PERSISTS_IGNORE_CATEGORIES`. `filter_persistent_ignores`, `registry_as_dict`. |
| `classifier.py` | Per-segment classification — single source of truth. `classify_flags`/`classify_segment`/`classify_segment_full`/`classify_entry`. `is_ignored_for`/`is_resolved_by_edit`/`is_suppressed_for`. `compute_is_boundary_adj` (raw rule, no suppression) + `_check_boundary_adj` (persisted-field short-circuit + suppression). qalqala persisted-field short-circuit (local import of `compute_qalqala_letter`). |
| `snapshot_classifier.py` | `classify_snapshot(snap)` — routes a loose SegSnapshot dict (history op-log shape) through `classify_segment`; no logic reimplemented. Used by save-flow history enrichment. |
| `detail.py` | `_build_detail_lists` — single entry walk producing every per-category detail array + `verse_segments` coverage map + `sequence_gaps` + `basmala_amin` (per-chapter scan, missed-Basmala augmentation). `_compute_surah_offsets` / `_word_ord` (prefix-sum, O(1) ordinals). Each item carries `classified_issues`. Also identity helpers `resolve_segment_by_uid` / `resolve_segment_for_issue` / `filter_stale_issues`. |
| `_missing.py` | `_build_missing_words` — verse coverage gaps → issue dicts with `auto_fix`/`auto_fix_up`/`auto_fix_down` targeting; merges `sequence_gaps`. |
| `_structural.py` | `_check_structural_errors` — reads `segments.json` (verse-aggregated) via `load_seg_verses`. Returns `(errors, missing_verses, stats)`. |

qalqala helper canonical path: `inspector/services/segments/qalqala.py::compute_qalqala_letter`. `services.qalqala` is an alias resolving to the same module (used by `classifier.py` fall-through and the retired perf report).

### Routes — `inspector/routes/segments/validation.py` (`/api/seg`, bp `seg_val`)

| route | handler | notes |
|---|---|---|
| `GET /api/seg/validate/<reciter>` | `seg_validate` | full-reciter validate. Cached via `cache.get/set_seg_validate_cache`; invalidated on save (`invalidate_seg_caches`). `orjson_cached_response`. **No per-chapter param** (dropped — accordions are global). |
| `GET /api/seg/stats/<reciter>` | `seg_stats` | `compute_stats`; cached `cache.get/set_seg_stats_cache`. |
| `GET /api/seg/edit-history/<reciter>` | `seg_edit_history` | `load_edit_history`. |

There is no separate `trigger-validation` route; `/validate` is the single classify entry point and the cache is the dedupe layer.

## Client — `inspector/frontend/src/tabs/segments/`

`utils/validation/`:

| File | Role |
|---|---|
| `classified-issues.ts` | Build/normalize per-segment issue records consumed by the UI from the response. |
| `card-lead-seg.ts` | Lead-segment selection for a card. |
| `conf-class.ts` | `getConfClass()` — CSS class from confidence score. |
| `missing-verse-context.ts` | Surrounding-segment lookup for a missing-verse card. |
| `refresh.ts` | Fetch `/api/seg/validate` → `setValidation`. |
| `resolve-issue.ts` | Mark issue resolved (ignore / fix / split-resolved). |
| `split-group.ts` | Group split-resolved issues into chains (consumes `split_group_index`). |
| `stale.ts` | Stale-state predicates — when classification needs re-run. |

`domain/registry.ts` — TS twin of `registry.py` (camelCase fields). Exports same derived category tuples + `filterPersistentIgnores` + `ERROR_CAT_LABELS`.

Store: `stores/validation.ts` — `segValidation` writable (`SegValidateResponse | null`), `splitGroupIndex` derived, `accordionViewActive` derived from `valUiOpenCategory`, `setValidation`/`clearValidation`.

Components: `components/validation/{ValidationPanel,ErrorCard,GenericIssueCard,MissingVersesCard,MissingWordsCard,WaslBoundary,AccordionGuideModal}.svelte`. `ValidationPanel` filters stale items by live uid (`filterStaleIssues`) before render and owns accordion order.

## Registry-pair invariant

`registry.py` ↔ `registry.ts` ↔ parent `validators/validate_segments.py` must align. Adding/reordering a category:

1. Add row to `_REGISTRY` in `inspector/services/validation/registry.py` (set `accordion_order` AND mind dict insertion position).
2. Mirror row in `inspector/frontend/src/tabs/segments/domain/registry.ts` (camelCase). `parity.test.ts` fails otherwise.
3. Add detection hook: per-segment → `classify_flags` in `classifier.py`; cross-segment scan → `detail.py` / `_missing.py` / `_structural.py`.
4. Wire the count into `category_counts` + a response array key in `__init__.py::validate_reciter_segments`.
5. Add accordion position in `ValidationPanel.svelte` and a card subcomponent if `card_type` is new.
6. Update parent `validators/validate_segments.py` if it should also fire post-pipeline.

`IssueDefinition` flags govern persistence/suppression: `can_ignore` (Ignore button), `auto_suppress` (edit writes cat into `ignored_categories` for per-segment scope), `persists_ignore` (survives save serialization — `filter_persistent_ignores` strips the rest before write).

## Persisted classifier fields

Two fields stamped on every `detailed.json` segment, read at validate time to collapse per-validate CPU to a dict lookup.

| field | type | source-of-truth helper | rule |
|---|---|---|---|
| `qalqala_letter` | `str \| None` | `services/segments/qalqala.py::compute_qalqala_letter` | last Arabic letter of `dk_text_for_ref(matched_ref)` if ∈ `QALQALA_LETTERS` (ق ط ب ج د), else `None` |
| `is_boundary_adj` | `bool` | `services/validation/classifier.py::compute_is_boundary_adj` | raw rule, NO suppression: one-word seg (`s_word==e_word`) outside muqattaʼat / single-word-verse / `STANDALONE_REFS` / `STANDALONE_WORDS` allow-lists |

Stamped by (all call the same source-of-truth helper → byte-equivalent across writers):
- **Save flow** — `services/segments/save.py::_stamp_persisted_classifier_fields(seg, single_word_verses)` on every mutated seg. `is_boundary_adj` computed structural-only (`canonical=None`).
- **Extraction pipeline** — `.local/extraction` outputs (passes `canonical` to capture the phonemic side, where applicable).
- **Backfill** — `scripts/backfills/backfill_qalqala_letter.py`, `scripts/backfills/backfill_boundary_adj.py`.

Read path (`classifier.py`):
- qalqala: `classify_flags` reads `seg["qalqala_letter"]` when the key is present; **legacy fall-through** computes `compute_qalqala_letter(seg)` (local import to avoid a load cycle). Same helper → identical value.
- boundary_adj: `_check_boundary_adj` short-circuits on `is_suppressed_for` first, then returns persisted `seg["is_boundary_adj"]` when present, else falls through to `compute_is_boundary_adj`. Persisted value is the raw rule; suppression layers on top at read time.

Text source: `compute_qalqala_letter` and `compute_is_boundary_adj` derive seg text from `dk_text_for_ref(matched_ref)` (Migration #5 dropped per-seg `matched_text`). The `seg.get("matched_text") or dk_text_for_ref(...)` fall-through is the back-compat path for any pre-Migration-5 seg still carrying `matched_text`.

**Phonemizer is out of the validate runtime.** `compute_is_boundary_adj` accepts `canonical` for back-compat but ignores it (retired in Migration #5 with `phonemes_asr`); the rule is structural-only. `validate_reciter_segments` passes `canonical=None`. The only `quranic_phonemizer` consumer left is the offline `scripts/backfills/backfill_boundary_adj.py`; no `canonical_phonemes.pkl` loads during validate; eager-boot init removed from `app.py`.

## Snapshot lifecycle

Save flow (`services/segments/save.py`) routes history op-log snapshots through `classify_snapshot` (→ `classify_segment`), stamping `classified_issues` on each `targets_before` / `targets_after` and `snapshots.{before,after}` dict (via `_history_visible_categories`, with `probe_failed_uids` so v2 flags appear in the delta). `snapshot_classifier.py` is distinct from the live pass only in that it derives positional inputs from the bare snapshot and skips heavy detail rendering — no separate classification logic.

The before/after category delta on each op record drives the per-batch resolved-issue stats in the edit-history view and the validation-summary line in the save-preview surface.

`failed` resolution: once a ref is committed the seg's confidence becomes 1.0 and the empty-`matched_ref` condition no longer holds, so the category auto-drops on the next validate.

## Bench / drift harness

`bench/` (`snapshot.py` / `drift.py` / `measure.py`) + committed canonical snapshots `bench/ground_truth/<slug>.json` are the drift gate for any change to a perf-sensitive validation path. The gate asserts **byte-equivalent per-category output** against the ground-truth snapshot across the WIP reciter set. Any change to compute placement, caching, parallelism, or a persisted-field writer must pass drift before landing.

Backfill scripts use **parallel-then-promote**: write to a staging path (`archive/backfill/<slug>/detailed.json`), drift-check in-memory against `bench/ground_truth/<slug>.json`, then atomically promote to `reciters/<slug>/detailed.json` only on byte-equivalent match. All persisted-field writers (save / extraction / backfill / classifier fall-through) must produce identical values — drift check is the only guarantee of that.

(The `bench/` tree and parent-repo `validators/` are gitignored / live outside the inspector working tree; paths above are canonical for when the harness is checked out.)