feat(ocr): opt-in batch OCR mode via the gateway's async batch routes

Add DOCUMENT_OCR_MODE=sync|batch (default sync). In batch mode the tier-3 OCR
processor submits documents to the embedding gateway's async Batch OCR routes
(POST /v1/ocr/batch + GET /v1/ocr/batch/{job_id}, astrolabe-cloud-website#372)
for ~50% cheaper large-corpus backfill. The direct Mistral OCR path is left
untouched. Tracked on Deck #332.

Batch jobs run minutes-hours, so the OCR tier cannot block (the procrastinate
worker reclaims jobs in `doing` after INGEST_STALLED_JOB_SECONDS). Instead it
submits, records the gateway job id in a new per-tenant `batch_ocr_jobs` table
(procrastinate args are immutable across retries), and raises a BatchPending
signal that TieredEscalationStrategy turns into a same-queue deferred re-poll —
releasing the worker slot between polls. On completion the per-page markdown is
indexed like the sync path; a failure or a job past
DOCUMENT_OCR_BATCH_MAX_WAIT_SECONDS marks the document parse-failed.

Batch is opt-in and gateway-only: with the direct mistral backend, no gateway
URL, or the inline/memory pipeline (which can't defer), it falls back to sync.
One batch job per document (coalescing N docs/job is a follow-up).

- embedding/gateway_batch_client.py: submit/poll client (reuses GatewayTokenProvider).
- vector/batch_ocr_store.py + migration 008: job tracking (portable SQLite+PG).
- document_processors/escalation.py: BatchPending control-flow signal.
- document_processors/ocr.py: batch state machine + sync fallback.
- vector/processor.py: thread doc identity to the OCR tier; raise BatchPending
  from the pending sentinel; propagate it as control flow (not a failure).
- vector/queue/procrastinate.py: BatchPending -> same-queue retry_in, exempt
  from the transient cap (bounded by the processor's deadline).
- config + docs; tests across client/store/processor/strategy/parse-tier.

1653 unit tests pass; ruff + ty green.

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

tests/unit/vector/test_parse_pdf_tier.py

@@ -97,3 +97,40 @@ async def test_hard_failure_returns_result_without_escalating(monkeypatch):
     reg.evaluate_escalation.assert_not_called()
     rec.assert_not_called()
     sup.assert_not_called()
+
+
+async def test_ocr_batch_pending_sentinel_raises_batch_pending():
+    """Batch OCR (Deck #332): the OCR tier's pending sentinel result is turned
+    into a BatchPending raise (same decision point as EscalateError), carrying
+    the processor's retry_in, and the escalation gate is never consulted."""
+    from nextcloud_mcp_server.document_processors.escalation import BatchPending
+    from nextcloud_mcp_server.document_processors.ocr import (
+        OCR_BATCH_PENDING_KEY,
+        OCR_BATCH_RETRY_IN_KEY,
+    )
+
+    result = ProcessingResult(
+        text="",
+        metadata={OCR_BATCH_PENDING_KEY: True, OCR_BATCH_RETRY_IN_KEY: 90},
+        processor="ocr",
+        success=False,
+    )
+    reg = _registry(result, decision=None)
+    with pytest.raises(BatchPending) as ei:
+        await processor._parse_pdf_tier(
+            reg, b"%PDF", "application/pdf", "scan.pdf", "ocr", settings=object()
+        )
+    assert ei.value.retry_in == 90
+    reg.evaluate_escalation.assert_not_called()
+
+
+async def test_options_threaded_to_process_tier():
+    """The OCR identity options are forwarded to process_tier (batch needs them)."""
+    result = ProcessingResult(text="clean", metadata={}, processor="ocr")
+    reg = _registry(result, decision=None)
+    opts = {"user_id": "u", "doc_id": "d", "doc_type": "file", "etag": "v"}
+    await processor._parse_pdf_tier(
+        reg, b"%PDF", "application/pdf", "f.pdf", "ocr", settings=object(), options=opts
+    )
+    # process_tier(content, content_type, filename, tier, options=...)
+    assert reg.process_tier.await_args.kwargs["options"] == opts

tests/unit/vector/test_tiered_escalation_strategy.py

@@ -14,6 +14,7 @@ from procrastinate.jobs import Job
 import nextcloud_mcp_server.vector.queue.procrastinate as pq
 from nextcloud_mcp_server.document_processors.escalation import (
     TIER_LADDER,
+    BatchPending,
     EscalateError,
     next_tier,
 )
@@ -120,3 +121,30 @@ class TestTieredEscalationStrategy:
             exception=ValueError("permanent"), job=_job(attempts=1)
         )
         assert decision is None
+
+    def test_batch_pending_defers_same_queue(self):
+        # Batch OCR re-poll (Deck #332): same-queue deferral after retry_in.
+        before = datetime.now(timezone.utc)
+        decision = self._strategy().get_retry_decision(
+            exception=BatchPending(retry_in=120), job=_job(queue=pq.INGEST_QUEUE_OCR)
+        )
+        after = datetime.now(timezone.utc)
+        assert decision is not None
+        assert decision.queue is None  # stays on its own tier queue
+        assert decision.retry_at is not None
+        lo = (decision.retry_at - after).total_seconds()
+        hi = (decision.retry_at - before).total_seconds()
+        assert lo <= 120 <= hi
+
+    def test_batch_pending_exempt_from_transient_cap(self):
+        # A batch can take hours -> many polls; the transient cap must NOT stop it
+        # (the OCR processor's own deadline terminates a stuck job instead).
+        decision = self._strategy(max_transient=5).get_retry_decision(
+            exception=BatchPending(retry_in=60), job=_job(attempts=999)
+        )
+        assert decision is not None and decision.retry_at is not None
+
+    def test_batch_pending_unwraps_exception_group(self):
+        group = ExceptionGroup("wrapped", [BatchPending(retry_in=60)])
+        decision = self._strategy().get_retry_decision(exception=group, job=_job())
+        assert decision is not None and decision.retry_at is not None