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>

nextcloud_mcp_server/vector/queue/procrastinate.py

@@ -328,13 +328,26 @@ class TieredEscalationStrategy(BaseRetryStrategy):
     def get_retry_decision(
         self, *, exception: BaseException, job: Job
     ) -> RetryDecision | None:
-        # Lazy import: EscalateError lives in the document stack, which the API
-        # pod (it also builds this App to defer) must not load. get_retry_decision
-        # runs only in the worker, where the stack is already imported.
-        from ...document_processors.escalation import EscalateError  # noqa: PLC0415
+        # Lazy import: these live in the document stack, which the API pod (it
+        # also builds this App to defer) must not load. get_retry_decision runs
+        # only in the worker, where the stack is already imported.
+        from ...document_processors.escalation import (  # noqa: PLC0415
+            BatchPending,
+            EscalateError,
+        )
 
         exc = _first_leaf(exception)
 
+        if isinstance(exc, BatchPending):
+            # Batch OCR job still in flight (Deck #332): defer a re-poll on the
+            # SAME queue after retry_in seconds. Deliberately exempt from the
+            # transient cap below — a batch job can take minutes-hours, so the
+            # poll count is unbounded here; the OCR processor's own deadline
+            # (DOCUMENT_OCR_BATCH_MAX_WAIT_SECONDS) is what terminates a stuck job.
+            # Releasing the worker between polls keeps the job out of `doing`, so
+            # it's never stall-reclaimed.
+            return RetryDecision(retry_in={"seconds": exc.retry_in})
+
         if isinstance(exc, EscalateError):
             queue = TIER_QUEUES.get(exc.to_tier)
             if queue is None: