feat: backend-agnostic vector-sync gauges (pending/documents/chunks)

The only queue metric, mcp_vector_sync_queue_size, was updated inline by the
single-user consumer (processor_task) but never by the multi-user consumer
(oauth_processor_task). On multi-user tenants (e.g. blackbox-demo, 5 users) the
gauge read 0 for 24h while the live anyio buffer held ~2214 pending documents
(shown by /api/v1/vector-sync/status). The "indexed" figure was also a chunk
count (16039 points ≈ 480 docs) mislabelled as documents.

Publish a consumer-independent snapshot from a periodic task
(vector/metrics_publisher.vector_sync_metrics_task), spawned in BOTH lifespan
task groups (single-user and multi-user) and every queue backend:
- mcp_vector_sync_pending_documents — outstanding work via
  ingest_status.get_ingest_pending() (anyio buffer depth or procrastinate
  todo+doing); also keeps the legacy queue_size gauge meaningful on all paths.
- mcp_vector_sync_indexed_documents — distinct documents, counted exactly and
  cheaply via the one chunk_index=0 point per document (no facet).
- mcp_vector_sync_indexed_chunks — total non-placeholder points.

The /api/v1/vector-sync/status endpoint now returns indexed_documents (distinct
docs) AND indexed_chunks separately, so documents and chunks are no longer
conflated. The publisher uses approximate Qdrant counts (every-N-seconds gauge);
the on-demand endpoint counts exactly. New knob:
VECTOR_SYNC_METRICS_REFRESH_INTERVAL (default 20s). Fail-safe: a metrics refresh
never disturbs ingest.

BREAKING CHANGE: /api/v1/vector-sync/status field `indexed_documents` now holds
the distinct-document count (was the chunk count); the chunk count moved to the
new `indexed_chunks` field. The Astrolabe UI + the nc_get_vector_sync_status MCP
tool / userinfo page are harmonized in a follow-up (Deck #195).

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

tests/unit/vector/test_metrics_publisher.py

@@ -0,0 +1,162 @@
+"""Unit tests for the vector-sync metrics publisher.
+
+Covers vector/metrics_publisher.py: the exact document/chunk counting
+(documents via the chunk_index=0 point) and the fail-safe snapshot publisher
+that fixes the queue gauge reading 0 on the multi-user consumer path.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import anyio
+import pytest
+
+from nextcloud_mcp_server.vector import metrics_publisher as mp
+from nextcloud_mcp_server.vector.ingest_status import IngestPending
+
+pytestmark = pytest.mark.unit
+
+_COLLECTION = "test_collection"
+
+
+def _count_obj(n: int) -> SimpleNamespace:
+    return SimpleNamespace(count=n)
+
+
+def _must_keys(flt) -> list[str | None]:
+    return [getattr(c, "key", None) for c in (flt.must or [])]
+
+
+class TestCountIndexed:
+    async def test_returns_documents_and_chunks(self) -> None:
+        qc = AsyncMock()
+        # count() is called for chunks first, then documents.
+        qc.count.side_effect = [_count_obj(16039), _count_obj(486)]
+
+        documents, chunks = await mp.count_indexed(qc, _COLLECTION)
+
+        assert (documents, chunks) == (486, 16039)
+        assert qc.count.await_count == 2
+
+    async def test_document_count_filters_on_chunk_index_zero(self) -> None:
+        qc = AsyncMock()
+        qc.count.side_effect = [_count_obj(10), _count_obj(3)]
+
+        await mp.count_indexed(qc, _COLLECTION)
+
+        # First call = chunks (placeholder filter only); second = documents
+        # (placeholder filter + chunk_index), the distinct-document trick.
+        chunks_filter = qc.count.await_args_list[0].kwargs["count_filter"]
+        docs_filter = qc.count.await_args_list[1].kwargs["count_filter"]
+        assert _must_keys(chunks_filter) == ["is_placeholder"]
+        assert _must_keys(docs_filter) == ["is_placeholder", "chunk_index"]
+
+
+class TestPublishVectorSyncMetrics:
+    @pytest.fixture(autouse=True)
+    def _stub_settings(self, monkeypatch) -> None:
+        settings = SimpleNamespace(
+            ingest_queue="memory",
+            get_collection_name=lambda: _COLLECTION,
+        )
+        monkeypatch.setattr(mp, "get_settings", lambda: settings)
+
+    @pytest.fixture
+    def gauges(self, monkeypatch) -> dict[str, MagicMock]:
+        g = {
+            name: MagicMock()
+            for name in (
+                "update_vector_sync_pending_documents",
+                "update_vector_sync_queue_size",
+                "update_vector_sync_indexed_documents",
+                "update_vector_sync_indexed_chunks",
+            )
+        }
+        for name, mock in g.items():
+            monkeypatch.setattr(mp, name, mock)
+        return g
+
+    async def test_publishes_all_gauges(self, monkeypatch, gauges) -> None:
+        monkeypatch.setattr(
+            mp,
+            "get_ingest_pending",
+            AsyncMock(return_value=IngestPending(pending=2214)),
+        )
+        qc = AsyncMock()
+        qc.count.side_effect = [_count_obj(16039), _count_obj(486)]
+        monkeypatch.setattr(mp, "get_qdrant_client", AsyncMock(return_value=qc))
+
+        await mp.publish_vector_sync_metrics(
+            task_producer=None, document_receive_stream=object()
+        )
+
+        gauges["update_vector_sync_pending_documents"].assert_called_once_with(2214)
+        # Legacy gauge kept meaningful on every consumer path.
+        gauges["update_vector_sync_queue_size"].assert_called_once_with(2214)
+        gauges["update_vector_sync_indexed_documents"].assert_called_once_with(486)
+        gauges["update_vector_sync_indexed_chunks"].assert_called_once_with(16039)
+
+    async def test_pending_failure_does_not_block_corpus_gauges(
+        self, monkeypatch, gauges
+    ) -> None:
+        # get_ingest_pending raising must not stop the indexed gauges (and must
+        # not propagate — a metrics refresh cannot disturb ingest).
+        monkeypatch.setattr(
+            mp, "get_ingest_pending", AsyncMock(side_effect=RuntimeError("queue down"))
+        )
+        qc = AsyncMock()
+        qc.count.side_effect = [_count_obj(10), _count_obj(3)]
+        monkeypatch.setattr(mp, "get_qdrant_client", AsyncMock(return_value=qc))
+
+        await mp.publish_vector_sync_metrics(
+            task_producer=None, document_receive_stream=object()
+        )
+
+        gauges["update_vector_sync_pending_documents"].assert_not_called()
+        gauges["update_vector_sync_indexed_documents"].assert_called_once_with(3)
+        gauges["update_vector_sync_indexed_chunks"].assert_called_once_with(10)
+
+    async def test_qdrant_failure_does_not_block_pending_gauge(
+        self, monkeypatch, gauges
+    ) -> None:
+        monkeypatch.setattr(
+            mp,
+            "get_ingest_pending",
+            AsyncMock(return_value=IngestPending(pending=42)),
+        )
+        monkeypatch.setattr(
+            mp, "get_qdrant_client", AsyncMock(side_effect=RuntimeError("qdrant down"))
+        )
+
+        await mp.publish_vector_sync_metrics(
+            task_producer=None, document_receive_stream=object()
+        )
+
+        gauges["update_vector_sync_pending_documents"].assert_called_once_with(42)
+        gauges["update_vector_sync_indexed_documents"].assert_not_called()
+
+
+class TestVectorSyncMetricsTask:
+    async def test_publishes_then_exits_on_shutdown(self, monkeypatch) -> None:
+        shutdown = anyio.Event()
+        published = 0
+
+        async def _fake_publish(task_producer, document_receive_stream) -> None:
+            nonlocal published
+            published += 1
+            shutdown.set()  # one pass, then stop the loop
+
+        monkeypatch.setattr(
+            mp, "publish_vector_sync_metrics", AsyncMock(side_effect=_fake_publish)
+        )
+        monkeypatch.setattr(
+            mp,
+            "get_settings",
+            lambda: SimpleNamespace(vector_sync_metrics_refresh_interval=0),
+        )
+
+        await mp.vector_sync_metrics_task(None, None, shutdown)
+
+        assert published == 1