test(usage): cover search metering hook; log dedup metering skip (round 4)

Round-4 claude-review findings (no blockers):

- 🟡 Untested server-layer metering hook (raised across rounds): extracted the
  nc_semantic_search embeddings_queries recording into a module-level
  record_search_usage() helper (mirroring record_indexing_usage) and added
  tests/unit/server/test_semantic_metering.py — value = query token count,
  flag-off no-op, None token → 0, doc_types metadata bounding, best-effort
  failure swallowed.
- 🟡 Dedup-hit skipped metering invisibly: the existing dedup info log now
  states "no embedding/usage recorded" so a "fewer embeddings_queries rows than
  expected" audit lands on the dedup path directly.

Deferred 🟢 nits (stated on the PR): search 0-token rows are recorded
deliberately (the query embedding ran; zero is a sum no-op) — documented in the
helper; embed_tokens closure locality and the OpenAI embed() dual path are
unchanged (correct as-is / separate refactor).

Deck #67.

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

tests/unit/server/__init__.py

@@ -0,0 +1 @@
+"""Unit tests for server-layer MCP tools."""

tests/unit/server/test_semantic_metering.py

@@ -0,0 +1,109 @@
+"""Unit tests for the search-path usage-metering helper (Deck #67).
+
+``record_search_usage`` records the billable ``embeddings_queries`` event for a
+semantic search. These pin the value mapping (query token count), the flag-off
+no-op, the doc_types metadata bounding, and the best-effort failure path —
+covering the server-tool metering wiring without standing up the full
+``nc_semantic_search`` tool.
+"""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nextcloud_mcp_server.server import semantic
+
+
+@pytest.fixture
+def store_spy(monkeypatch):
+    """Patch UsageEventStore.shared() to return a spy store."""
+    store = MagicMock()
+    store.record_usage_event = AsyncMock()
+    monkeypatch.setattr(
+        semantic.UsageEventStore, "shared", AsyncMock(return_value=store)
+    )
+    return store
+
+
+@pytest.mark.unit
+async def test_records_query_token_count(store_spy):
+    """The event value is the query embedding's token count."""
+    await semantic.record_search_usage(
+        enabled=True,
+        user_id="alice",
+        fusion="rrf",
+        doc_types=["note", "file"],
+        token_count=42,
+    )
+
+    store_spy.record_usage_event.assert_awaited_once()
+    kwargs = store_spy.record_usage_event.await_args.kwargs
+    assert kwargs["metric"] == "embeddings_queries"
+    assert kwargs["value"] == 42
+    assert kwargs["enabled"] is True
+    assert kwargs["metadata"]["user_id"] == "alice"
+    assert kwargs["metadata"]["fusion"] == "rrf"
+    assert kwargs["metadata"]["doc_types"] == ["note", "file"]
+
+
+@pytest.mark.unit
+async def test_disabled_is_noop(store_spy):
+    """Flag off → no store access, no event."""
+    await semantic.record_search_usage(
+        enabled=False,
+        user_id="alice",
+        fusion="rrf",
+        doc_types=None,
+        token_count=10,
+    )
+    store_spy.record_usage_event.assert_not_awaited()
+
+
+@pytest.mark.unit
+async def test_none_token_count_records_zero(store_spy):
+    """A missing token count (pre-embed error) records value 0, not None."""
+    await semantic.record_search_usage(
+        enabled=True,
+        user_id="alice",
+        fusion="dbsf",
+        doc_types=None,
+        token_count=None,
+    )
+    kwargs = store_spy.record_usage_event.await_args.kwargs
+    assert kwargs["value"] == 0
+    # None and [] both normalize to null for consistent IS NULL counting.
+    assert kwargs["metadata"]["doc_types"] is None
+
+
+@pytest.mark.unit
+async def test_doc_types_metadata_is_bounded(store_spy):
+    """A large doc_types list is truncated to the metadata cap."""
+    many = [f"type-{i}" for i in range(40)]
+    await semantic.record_search_usage(
+        enabled=True,
+        user_id="alice",
+        fusion="rrf",
+        doc_types=many,
+        token_count=5,
+    )
+    recorded = store_spy.record_usage_event.await_args.kwargs["metadata"]["doc_types"]
+    assert recorded == many[: semantic._USAGE_METADATA_MAX_DOC_TYPES]
+
+
+@pytest.mark.unit
+async def test_store_failure_is_swallowed(monkeypatch):
+    """A store-construction failure is logged, never raised into the search."""
+    monkeypatch.setattr(
+        semantic.UsageEventStore,
+        "shared",
+        AsyncMock(side_effect=RuntimeError("boom")),
+    )
+
+    # Must not raise.
+    await semantic.record_search_usage(
+        enabled=True,
+        user_id="alice",
+        fusion="rrf",
+        doc_types=None,
+        token_count=7,
+    )