fix(ingest): address review round 2 (Literal reason + exhaustive branch + test)

- escalation: EscalationDecision.reason is now Literal["empty_text",
  "low_confidence"] (parity with kind; ty catches a bad label at call sites).
- processor: nest the decision handling so the hop branch is reached via an
  explicit else under `if decision is not None` — exhaustive over the Literal
  kind, no None-attribute risk.
- tests: add the "OCR processor unregistered (not just disabled) → None"
  quadrant, locking in absent != suppressed.

Deck #324.

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

nextcloud_mcp_server/document_processors/escalation.py

@@ -49,7 +49,7 @@ class EscalationDecision:
 
     kind: Literal["hop", "suppressed"]
     to_tier: str
-    reason: str  # empty_text | low_confidence
+    reason: Literal["empty_text", "low_confidence"]
 
 
 def next_tier(current: str) -> str | None:

nextcloud_mcp_server/vector/processor.py

@@ -157,10 +157,12 @@ async def _parse_pdf_tier(
         decision = registry.evaluate_escalation(
             result, content, tier, settings, filename=filename
         )
-        if decision is not None and decision.kind == "suppressed":
+        if decision is not None:
-            # The ideal next tier (e.g. ocr) is disabled, so we do NOT hop: index
+            if decision.kind == "suppressed":
-            # this tier's output as terminal and record the would-be escalation
+                # The ideal next tier (e.g. ocr) is disabled, so we do NOT hop:
-            # so operators see the latent demand ("what-if OCR enabled"; #324).
+                # index this tier's output as terminal and record the would-be
+                # escalation so operators see the latent demand ("what-if OCR
+                # enabled"; #324).
                 record_document_escalation_suppressed(
                     tier, decision.to_tier, decision.reason
                 )
@@ -172,7 +174,7 @@ async def _parse_pdf_tier(
                     decision.to_tier,
                     decision.reason,
                 )
-        elif decision is not None:
+            else:  # "hop" — the Literal kind makes this branch exhaustive.
                 record_document_escalation(tier, decision.to_tier, decision.reason)
                 logger.info(
                     "Escalating %s %s->%s (reason=%s)",

tests/unit/test_registry_tiering.py

@@ -482,3 +482,19 @@ def test_evaluate_escalation_structured_hop_not_suppressed_when_ocr_off(monkeypa
     )
     decision = r.evaluate_escalation(res, b"%PDF", "fast", _Settings(ocr=False))
     assert decision == EscalationDecision("hop", "structured", "low_confidence")
+
+
+def test_evaluate_escalation_terminal_when_ocr_unregistered_and_off(monkeypatch):
+    """No OCR processor registered at all (not merely disabled) → genuinely
+    terminal: returns None, NOT a suppressed decision. 'Absent' != 'disabled'."""
+    monkeypatch.setattr(reg_mod, "record_document_classification", MagicMock())
+    r = _registry((_Fake("fast", "fast"), 20))  # only fast; no ocr processor
+    res = ProcessingResult(
+        text="",
+        metadata={
+            "page_count": 1,
+            "page_boundaries": [{"page": 1, "start_offset": 0, "end_offset": 0}],
+        },
+        processor="fast",
+    )
+    assert r.evaluate_escalation(res, b"%PDF", "fast", _Settings(ocr=False)) is None