feat: quality + scan OCR escalation trigger (junk-text-layer scans)

The hot-path classifier escalated to OCR purely on character count, so a
scanned/handwritten PDF with a low-quality embedded text layer (>16 chars/page
but garbled) routed `fast` and indexed the junk -- e.g. Student 147.pdf's
"Little Acoms Primary"/"0110912020", which pollutes the vector and demotes the
doc in search (Deck #207).

- classifier: recalibrate `_text_quality` with a long-token-fraction term that
  detects word-merging (dropped inter-word spaces) -- the dominant junk-layer
  failure the old whitespace/overlong(>20) terms missed. Measured: the Student
  147 scan ~0.42 (60% pages junk) vs >=0.94 for clean digital docs.
- classify_from_text now routes on quality + scan: a page is OCR-worthy if
  near-empty OR low text-quality OR (when OCR + scan detection are enabled) it's
  mostly a raster image. New `image_coverage_per_page` re-opens the PDF for the
  scan signal, so that cost is paid only by OCR-opted-in tenants. Thresholds are
  passed in from per-tenant settings (keyword-only).
- config: 4 per-tenant settings -- DOCUMENT_OCR_MIN_TEXT_QUALITY (0.5),
  DOCUMENT_OCR_PAGE_FRACTION (0.5), DOCUMENT_OCR_MIN_PAGE_CHARS (16),
  DOCUMENT_OCR_DETECT_SCANNED (true) -- with range validators.
- metrics: new astrolabe_document_ocr_page_fraction histogram (the value the
  page-fraction threshold acts on) alongside document_text_quality, so operators
  can tune the OCR escalation per tenant (quality vs cost).

Escalation gate, OCR backends, and off-by-default behavior unchanged (#858).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/unit/test_registry_tiering.py

@@ -65,10 +65,23 @@ class _Fake(DocumentProcessor):
 
 
 class _Settings:
-    def __init__(self, engine="pypdfium2", classify=True, ocr=False):
+    def __init__(
+        self,
+        engine="pypdfium2",
+        classify=True,
+        ocr=False,
+        min_text_quality=0.5,
+        page_fraction=0.5,
+        min_page_chars=16,
+        detect_scanned=False,
+    ):
         self.document_tier1_engine = engine
         self.document_classify_enabled = classify
         self.document_ocr_enabled = ocr
+        self.document_ocr_min_text_quality = min_text_quality
+        self.document_ocr_page_fraction = page_fraction
+        self.document_ocr_min_page_chars = min_page_chars
+        self.document_ocr_detect_scanned = detect_scanned
 
 
 def _registry(*procs: tuple[DocumentProcessor, int]) -> ProcessorRegistry:
@@ -113,6 +126,11 @@ async def test_records_classification(monkeypatch):
     r = _registry((_Fake("fast", "fast"), 20))
     await r.process(b"%PDF-1.7", "application/pdf")
     rec.assert_called_once()
+    # recommended_tier, flags, mean_text_quality, ocr_page_fraction all threaded
+    # through (the last two feed the per-tenant tuning histograms).
+    args = rec.call_args.args
+    assert len(args) == 4
+    assert isinstance(args[0], str) and isinstance(args[3], float)
 
 
 async def test_classify_disabled_skips_recording(monkeypatch):