feat: admin TOC Validator screen (339595)

[Us3r369]

Summary

Adds an admin TOC Validator screen (ticket 339595) that surfaces documents whose body content is at risk of being hidden from Search because of how its sections are tagged.

Search's default content type filter only returns chunks whose section type is one of the "real content" types (executive_summary, context, methodology, findings, conclusions, recommendations, other). Everything else — front_matter, acronyms, annexes, appendix, bibliography, introduction — is excluded by default. Tagging is automatic at upload, so a body section mis-tagged as e.g. annexes silently disappears from default search results.

Each document carries a human-set body page range in its source metadata (Introduction - before beginning of Annexes). This feature checks that every section falling inside that range uses a default-included type, and lets an admin verify/fix the classification.

Screenshots

What it does

• Lists documents (reusing the Documents Library /documents endpoint), with an indication of any prior validation result.
• Select some or all documents → Run validation → each verdict is shown and persisted; rows that were added/changed by the run are highlighted.
• Metadata and Contents links open the same modals as the Documents Library, so a flagged result can be checked — and edited — against the real document. Editing a classification re-validates that document.

Verdicts: pass (all in-range sections included), fail (an excluded type inside the body range), skipped (no range / no classified contents).

The check inspects the current classification only; it never re-tags.

How it's built

Shared logic — extracted into pipeline/validation/section_inclusion.py so the backend service and the existing offline eval script (tests/evaluation/section_inclusion/) share one implementation (the script now imports it; no behaviour change).

Backend (superuser-only, rate-limited) in ui/backend/routes/toc_validator.py + services/toc_validator.py:

• POST /toc-validator/run — validate selected docs, persist, return results
• GET /toc-validator/results — stored results for the screen on load

Frontend — new admin tab: TocValidatorManager + TocValidatorTable + TocValidationResultCell + useTocValidator, reusing MetadataModal/TocModal and the app's design tokens + shared badge/table/button classes.

Persistence — note for reviewers

Results are stored per document under a sys_toc_validation field via merge_doc_sys_fields (the same mechanism sys_toc_approved uses). No Alembic migration: the per-data-source docs_<source> tables are created/altered dynamically at runtime by the ensure_* helpers — they are not Alembic-managed except for uneg, so a migration would only (wrongly) touch that one source. This matches the existing per-doc-field precedent.

A finding worth a decision

Across the WFP corpus the dominant failure is sections tagged introduction inside the body range. That is systemic, not per-document mis-tagging: the body range starts at the introduction, and introduction is not in the default-included set (and has no checkbox in Search settings). The genuinely actionable mis-tags are annexes/acronyms/bibliography/front_matter appearing mid-body (e.g. a report whose Findings/Recommendations chapters were labelled annexes because headings contained "(EQs 1-5, Annex 8)"). Whether to add introduction to the defaults is a product decision this tool now makes visible.

Testing

• Backend: unit tests for the shared logic (test_section_inclusion.py) and service (test_toc_validator_service.py); service round-tripped against real WFP data (persist + read-back).
• Frontend: tocValidator.test.tsx (manager/table/result cell); full suite 518 passing, tsc clean, eslint zero warnings.
• Verified the two endpoints register on the running API and are superuser-gated.

Docs: docs/admin/toc-validator.md (added to the sidebar).

🤖 Generated with Claude Code

[Us3r369]

When testing locally, the TOC validator flagged many cases with section type "introduction" outside of the "Introduction - before beginning of Annexes (start_page_number, end_page_number)" range. Flagging this here to discuss if this is expected and acceptable or should be adjusted!

[dividor]

Please ensure the table column is clearly labelled so a person reading it knows exactly what it is 'Table of Contents review'. Also make sure it's filterable if not already.

[Us3r369]

@dividor adjusted column header and added filters in latest commit