refactor(usage): address round-1 review on PR #871

- store: add optional `enabled` param to record_usage_event so hot-path
  callers (nc_semantic_search) pass the already-resolved flag instead of
  forcing a second uncached Settings build (ADR-024); falls back to
  get_settings() when None so the store stays self-gating for standalone
  use.
- hooks: thread enabled= through both call sites; bump the outer
  shared()/construction failure log from debug → warning so "metering
  enabled but no billing data" is visible at the default INFO level.
- migration: instantiate postgresql.JSONB() to match the sibling
  TIMESTAMP(timezone=True) column.
- tests: fix the misleading "asyncpg returns JSONB as a JSON string"
  comment; add occurred_at dialect round-trip test and an enabled-param
  short-circuit test.

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

nextcloud_mcp_server/alembic/versions/20260610_1200_007_add_usage_events.py

@@ -60,7 +60,7 @@ def upgrade() -> None:
         # (json.dumps) on SQLite.
         sa.Column(
             "metadata",
-            postgresql.JSONB if is_pg else sa.Text,
+            postgresql.JSONB() if is_pg else sa.Text,
             nullable=True,
         ),
     )

nextcloud_mcp_server/server/semantic.py

@@ -534,9 +534,16 @@ def configure_semantic_tools(mcp: FastMCP):
                             "fusion": fusion,
                             "doc_types": doc_types,
                         },
+                        # Pass the already-resolved flag so the store doesn't
+                        # rebuild Settings on this hot query path (ADR-024).
+                        enabled=settings.usage_metering_enabled,
                     )
                 except Exception:
-                    logger.debug(
+                    # Reached only when shared()/store construction itself
+                    # raises (record_usage_event swallows its own write
+                    # failures). Metering is on, so warn — a silent DEBUG line
+                    # would hide "operator enabled metering but gets no data".
+                    logger.warning(
                         "usage metering hook (embeddings_queries) skipped",
                         exc_info=True,
                     )

nextcloud_mcp_server/usage/store.py

@@ -72,6 +72,7 @@ class UsageEventStore:
         occurred_at: datetime | None = None,
         metadata: dict[str, Any] | None = None,
         event_id: str | None = None,
+        enabled: bool | None = None,
     ) -> None:
         """Record one billable usage event (best-effort, flag-gated).
 
@@ -86,8 +87,16 @@ class UsageEventStore:
             metadata: Optional rawest-unit context (provider, model, tokens,
                 doc_type, ...). Stored as JSONB (Postgres) / JSON text (SQLite).
             event_id: Optional idempotency key; defaults to a fresh UUID4.
+            enabled: The resolved ``USAGE_METERING_ENABLED`` value. ``None``
+                (default) re-reads it via ``get_settings()`` so the store stays
+                self-gating for standalone/test use. Hot-path callers that
+                already hold the flag should pass it to avoid a second uncached
+                ``Settings`` build (``get_settings()`` is non-cached per
+                ADR-024 and ``nc_semantic_search`` is on the query path).
         """
-        if not get_settings().usage_metering_enabled:
+        if enabled is None:
+            enabled = get_settings().usage_metering_enabled
+        if not enabled:
             return
 
         start = time.time()

nextcloud_mcp_server/vector/processor.py

@@ -839,9 +839,16 @@ async def _index_document(
                             "user_id": doc_task.user_id,
                             "total_chars": total_chars,
                         },
+                        # Pass the already-resolved flag so the store doesn't
+                        # rebuild Settings here (ADR-024).
+                        enabled=settings.usage_metering_enabled,
                     )
                 except Exception:
-                    logger.debug(
+                    # Reached only when shared()/store construction itself
+                    # raises (record_usage_event swallows its own write
+                    # failures). Metering is on, so warn rather than hide the
+                    # "enabled but no billing data" case in DEBUG logs.
+                    logger.warning(
                         "usage metering hook (pages_chunks) skipped", exc_info=True
                     )