feat(ingest): record suppressed OCR escalations (what-if-OCR signal)

OCR is the paid, opt-in tier (DOCUMENT_OCR_ENABLED, default off). The per-tier
escalation gate already declines to hop to OCR when it's disabled (the pre-OCR
tier is terminal — no surprise cost), but that left operators blind to how much
OCR demand exists.

evaluate_escalation now returns a structured EscalationDecision:
- "hop"        — a higher tier can run; the caller raises EscalateError (queue-hop).
- "suppressed" — the ideal next tier (e.g. ocr) exists but is DISABLED; the caller
                 indexes the current tier's output as terminal and records the
                 would-be hop on the new astrolabe_document_escalation_suppressed_total
                 {from_tier,to_tier,reason} counter instead of hopping.
- None         — index as-is (good text, or no such tier at all).

So with OCR off, escalation_suppressed_total{to_tier="ocr"} is the latent OCR
demand an operator weighs before enabling OCR; enabling it converts these into
real document_escalation_total{to_tier="ocr"} hops. next_available_tier gains an
ignore_enabled flag to compute the *ideal* (enabled-gate-ignored) target.

Tests: registry suppressed vs hop vs terminal (incl. structured-hop-not-suppressed
when OCR off but structured available); _parse_pdf_tier records suppressed +
indexes without raising.

Deck #324 (parent #323).

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

nextcloud_mcp_server/vector/processor.py

@@ -28,6 +28,7 @@ from nextcloud_mcp_server.models.deck import DeckCard
 from nextcloud_mcp_server.observability.metrics import (
     record_document_chunks,
     record_document_escalation,
+    record_document_escalation_suppressed,
     record_document_parse_failed,
     record_embedding,
     record_embedding_tokens,
@@ -156,17 +157,35 @@ async def _parse_pdf_tier(
         decision = registry.evaluate_escalation(
             result, content, tier, settings, filename=filename
         )
-        if decision is not None:
-            to_tier, reason = decision
-            record_document_escalation(tier, to_tier, reason)
+        if decision is not None and decision.kind == "suppressed":
+            # The ideal next tier (e.g. ocr) is disabled, so we do NOT hop: 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
+            )
+            logger.info(
+                "Escalation suppressed for %s %s->%s (reason=%s; %s disabled), "
+                "indexing at %s",
+                filename or "<bytes>",
+                tier,
+                decision.to_tier,
+                decision.reason,
+                decision.to_tier,
+                tier,
+            )
+        elif decision is not None:
+            record_document_escalation(tier, decision.to_tier, decision.reason)
             logger.info(
                 "Escalating %s %s->%s (reason=%s)",
                 filename or "<bytes>",
                 tier,
-                to_tier,
-                reason,
+                decision.to_tier,
+                decision.reason,
+            )
+            raise EscalateError(
+                from_tier=tier, to_tier=decision.to_tier, reason=decision.reason
             )
-            raise EscalateError(from_tier=tier, to_tier=to_tier, reason=reason)
     return result