claude-smart 0.2.49 → 0.2.50

package/plugin/vendor/reflexio/reflexio/server/routes/evaluation.py

@@ -29,6 +29,8 @@ from reflexio.models.api_schema.eval_overview_schema import (
 from reflexio.models.api_schema.retriever_schema import (
     GetAgentSuccessEvaluationResultsRequest,
     GetEvaluationResultsViewResponse,
+    GetRetrievedLearningEvaluationResultsRequest,
+    GetRetrievedLearningEvaluationResultsResponse,
 )
 from reflexio.models.api_schema.ui.converters import (
     to_evaluation_result_view,
@@ -48,6 +50,12 @@ from reflexio.server.services.agent_success_evaluation.regen_jobs import (
 from reflexio.server.services.agent_success_evaluation.runner import (
     run_group_evaluation,
 )
+from reflexio.server.services.storage.storage_base.evaluation_state_keys import (
+    build_grade_on_demand_cache_key,
+)
+from reflexio.server.services.storage.storage_base.retrieved_learning_state import (
+    session_fingerprint,
+)
 
 logger = logging.getLogger(__name__)
 router = APIRouter()
@@ -90,28 +98,35 @@ def _grade_on_demand_cache_key(
     # injective: distinct component tuples can never collapse to the same key even
     # when a component itself contains the ``::`` delimiter. Keeps the prefix intact
     # for prefix-based filtering and the key human-readable for inspection.
-    parts = "::".join(
-        f"{len(s)}:{s}" for s in (org_id, session_id, agent_version, evaluation_name)
+    # Delegates to the shared builder so governance erasure scrubs the exact
+    # same keys this route writes.
+    return build_grade_on_demand_cache_key(
+        org_id, session_id, agent_version, evaluation_name
     )
-    return f"{_GRADE_ON_DEMAND_CACHE_KEY_PREFIX}::{parts}"
 
 
 def _read_grade_on_demand_cache(
-    storage: Any, cache_key: str, *, now: int
-) -> int | None:
-    """Return the cached ``result_id`` if a valid entry exists, else None.
+    storage: Any, cache_key: str, *, now: int, user_id: str, session_id: str
+) -> tuple[int | None, str | None] | None:
+    """Return the cached ``(result_id, retrieved_learning_status)`` if valid.
 
-    Returns None on three conditions: no entry, malformed entry, or entry
-    whose ``last_graded_at`` is older than the 24h TTL. Keeps the handler
-    body focused on the happy path.
+    Returns None on: no entry, malformed entry, entry older than the 24h TTL,
+    or — for entries carrying retrieved-learning fields — a session whose
+    retrieved-learning state no longer matches the cached fingerprint (a later
+    publish/delete changed the session, so cached completion must not be
+    claimed). Legacy entries without retrieved fields stay valid and report
+    ``retrieved_learning_status=None``.
 
     Args:
         storage: The request's storage backend.
         cache_key (str): Key produced by ``_grade_on_demand_cache_key``.
         now (int): Current Unix-seconds wall-clock timestamp.
+        user_id (str): Session owner, for retrieved-state revalidation.
+        session_id (str): The cached session, for retrieved-state revalidation.
 
     Returns:
-        int | None: Cached result_id when fresh, else None.
+        tuple | None: ``(result_id, retrieved_learning_status)`` when fresh,
+        else None.
     """
     cached_state = storage.get_operation_state(cache_key)
     if not cached_state:
@@ -125,7 +140,27 @@ def _read_grade_on_demand_cache(
     if (now - last_graded_at) >= _GRADE_ON_DEMAND_CACHE_TTL_SECONDS:
         return None
     cached_result_id = state.get("result_id")
-    return cached_result_id if isinstance(cached_result_id, int) else None
+    if not isinstance(cached_result_id, int):
+        return None
+    cached_fingerprint = state.get("retrieved_learning_fingerprint")
+    cached_retrieved_status = state.get("retrieved_learning_status")
+    if isinstance(cached_fingerprint, str) and cached_fingerprint:
+        # Recompute the CURRENT session fingerprint — a later publish/delete
+        # changes it without touching any state row — and require the
+        # persisted terminal state to still match it and the cached status.
+        current_fingerprint = session_fingerprint(
+            storage.load_bounded_retrieved_learning_snapshot(user_id, session_id)
+        )
+        if current_fingerprint != cached_fingerprint:
+            return None
+        current = storage.get_matching_retrieved_learning_terminal_state(
+            user_id, session_id, current_fingerprint
+        )
+        if current is None or current.get("status") != cached_retrieved_status:
+            return None
+    return cached_result_id, (
+        cached_retrieved_status if isinstance(cached_retrieved_status, str) else None
+    )
 
 
 def _resolve_session_user_id(storage: Any, session_id: str) -> str | None:
@@ -157,6 +192,7 @@ def _find_fresh_result_id(
     agent_version: str,
     evaluation_name: str,
     previous_result_ids: set[int],
+    accept_existing: bool,
 ) -> int | None:
     """Locate the result_id written by the most-recent grade for this session.
 
@@ -170,6 +206,8 @@ def _find_fresh_result_id(
         agent_version (str): The version dimension.
         evaluation_name (str): Evaluator/result namespace to isolate readback.
         previous_result_ids (set[int]): Matching rows observed before grading.
+        accept_existing (bool): Whether a completed grade may have updated an
+            existing row in place, as the Supabase backend does.
 
     Returns:
         int | None: result_id of the latest matching row, or None if the
@@ -182,9 +220,11 @@ def _find_fresh_result_id(
         agent_version=agent_version,
     )
     fresh_result_ids = [rid for rid in result_ids if rid not in previous_result_ids]
-    if not fresh_result_ids:
-        return None
-    return max(fresh_result_ids)
+    if fresh_result_ids:
+        return max(fresh_result_ids)
+    if accept_existing and result_ids:
+        return max(result_ids)
+    return None
 
 
 @router.post(
@@ -217,6 +257,28 @@ def get_agent_success_evaluation_results(
     )
 
 
+@router.post(
+    "/api/get_retrieved_learning_evaluation_results",
+    response_model=GetRetrievedLearningEvaluationResultsResponse,
+)
+def get_retrieved_learning_evaluation_results(
+    request: GetRetrievedLearningEvaluationResultsRequest,
+    org_id: str = Depends(default_get_org_id),
+) -> GetRetrievedLearningEvaluationResultsResponse:
+    """Get per-learning retrieved-learning evaluation verdicts.
+
+    Args:
+        request (GetRetrievedLearningEvaluationResultsRequest): Optional
+            user/session filters + limit.
+        org_id (str): Organization ID.
+
+    Returns:
+        GetRetrievedLearningEvaluationResultsResponse: Matching verdicts.
+    """
+    reflexio = reflexio_cache.get_reflexio(org_id=org_id)
+    return reflexio.get_retrieved_learning_evaluation_results(request)
+
+
 @router.post(
     "/api/get_evaluation_overview",
     response_model=GetEvaluationOverviewResponse,
@@ -417,15 +479,8 @@ def grade_on_demand(
     )
     now = int(datetime.now(UTC).timestamp())
 
-    cached_result_id = _read_grade_on_demand_cache(storage, cache_key, now=now)
-    if cached_result_id is not None:
-        return GradeOnDemandResponse(
-            session_id=payload.session_id,
-            result_id=cached_result_id,
-            cached=True,
-            skipped_reason=None,
-        )
-
+    # User resolution happens before the cache read: revalidating a cached
+    # retrieved-learning status needs the session owner's id.
     user_id = _resolve_session_user_id(storage, payload.session_id)
     if user_id is None:
         return GradeOnDemandResponse(
@@ -435,6 +490,19 @@ def grade_on_demand(
             skipped_reason="NO_REQUESTS",
         )
 
+    cached = _read_grade_on_demand_cache(
+        storage, cache_key, now=now, user_id=user_id, session_id=payload.session_id
+    )
+    if cached is not None:
+        cached_result_id, cached_retrieved_status = cached
+        return GradeOnDemandResponse(
+            session_id=payload.session_id,
+            result_id=cached_result_id,
+            cached=True,
+            skipped_reason=None,
+            retrieved_learning_status=cached_retrieved_status,
+        )
+
     previous_result_ids = set(
         storage.get_agent_success_evaluation_result_ids(
             user_id=user_id,
@@ -455,7 +523,7 @@ def grade_on_demand(
     # The cache key namespaces are distinct so the two markers do not
     # interfere; the explicit force_regenerate=True here is what makes
     # an on-demand grade always do real work on a cache miss.
-    run_group_evaluation(
+    outcome = run_group_evaluation(
         org_id=org_id,
         user_id=user_id,
         session_id=payload.session_id,
@@ -473,18 +541,44 @@ def grade_on_demand(
         agent_version=payload.agent_version,
         evaluation_name=evaluation_name,
         previous_result_ids=previous_result_ids,
+        accept_existing=outcome.agent_success_status == "complete",
     )
 
-    storage.upsert_operation_state(
-        cache_key,
-        {"last_graded_at": now, "result_id": result_id},
-    )
+    # Cache only settled outcomes. A terminal retrieved status is cached with
+    # its fingerprint ONLY after confirming the persisted state still
+    # linearizes at that fingerprint (a concurrent publish would have changed
+    # it); the cache read revalidates again, so a lost race here can never
+    # serve stale completion. Degraded/failed/pending/stale/superseded
+    # retrieved outcomes are not cached at all — the user's next explicit
+    # click must retry rather than short-circuit.
+    retrieved_status = outcome.retrieved_learning_status
+    if retrieved_status in ("complete", "not_applicable") and (
+        outcome.retrieved_learning_fingerprint
+    ):
+        confirmed = storage.get_matching_retrieved_learning_terminal_state(
+            user_id, payload.session_id, outcome.retrieved_learning_fingerprint
+        )
+        cache_entry: dict[str, Any] = {"last_graded_at": now, "result_id": result_id}
+        if confirmed is not None and confirmed.get("status") == retrieved_status:
+            cache_entry["retrieved_learning_status"] = retrieved_status
+            cache_entry["retrieved_learning_fingerprint"] = (
+                outcome.retrieved_learning_fingerprint
+            )
+            storage.upsert_operation_state(cache_key, cache_entry)
+    elif retrieved_status == "skipped":
+        # Retrieved evaluation not applicable to this deployment/session
+        # shape; keep the legacy agent-success-only cache behavior.
+        storage.upsert_operation_state(
+            cache_key,
+            {"last_graded_at": now, "result_id": result_id},
+        )
 
     return GradeOnDemandResponse(
         session_id=payload.session_id,
         result_id=result_id,
         cached=False,
         skipped_reason=None,
+        retrieved_learning_status=retrieved_status,
     )
 
 

package/plugin/vendor/reflexio/reflexio/server/routes/system.py

@@ -13,6 +13,7 @@ from fastapi import (
     Request,
     status,
 )
+from fastapi.responses import JSONResponse
 
 from reflexio.models.api_schema.retriever_schema import (
     GetDashboardStatsRequest,
@@ -55,9 +56,27 @@ def root() -> dict[str, str]:
     }
 
 
-@router.get("/health")
-async def health_check() -> dict[str, str]:
-    """Health check endpoint for ECS/container orchestration."""
+@router.get("/health", response_model=None)
+async def health_check() -> dict[str, str] | JSONResponse:
+    """Health check endpoint for ECS/container orchestration.
+
+    When the in-process-embedder warm-before-ready gate is active (a future
+    ``REFLEXIO_EMBEDDING_PROVIDER=inprocess`` + ``local/*`` deployment) and the
+    embedder has not finished loading, return HTTP 503 so the load balancer
+    holds traffic until the model is warm. In every other configuration — the
+    current daemon-mode prod state included — the gate is inactive and this
+    returns exactly the historical 200 body.
+    """
+    from reflexio.server.llm.providers.embedder_warmup import (
+        inprocess_local_gate_active,
+        is_embedder_ready,
+    )
+
+    if inprocess_local_gate_active() and not is_embedder_ready():
+        return JSONResponse(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            content={"status": "starting"},
+        )
     return {"status": "healthy"}
 
 

package/plugin/vendor/reflexio/reflexio/server/scheduling.py

@@ -19,6 +19,9 @@ set of hooks so no observable behaviour changes:
   ``start`` is a logged no-op when a feature gate is off).
 - :meth:`_on_started` / :meth:`_on_stopped` emit each scheduler's own start/stop
   log line (through its own module logger, so output is byte-identical).
+- ``leader_gate`` (optional): a fleet-coordination gate consulted before each
+  tick; ``None`` (the default and the OSS-local case) preserves today's
+  always-tick behavior byte-for-byte.
 
 A scheduler whose loop is materially different (e.g. a bounded-attempt retrier
 that waits *before* each attempt and exits on first success) may override
@@ -31,7 +34,31 @@ nothing from ``reflexio_ext``.
 
 from __future__ import annotations
 
+import logging
 import threading
+from typing import Protocol
+
+logger = logging.getLogger(__name__)
+
+# How long a non-leader waits before re-checking the gate. Fixed (no interval
+# memoization): a follower that becomes leader starts ticking within <=60s.
+_FOLLOWER_POLL_SECONDS: float = 60.0
+
+
+class LeaderGate(Protocol):
+    """Fleet-coordination gate consulted before each tick.
+
+    Implementations must NEVER raise from ``should_run`` — error handling
+    (including fail-open) lives inside the implementation (spec §4.1). The
+    scheduler base nonetheless defends against a contract violation: if
+    ``should_run`` raises anyway, the base logs the error and fails open
+    (runs the tick) rather than trusting the contract blindly and letting the
+    daemon thread die silently.
+    """
+
+    def should_run(self) -> bool:
+        """Return whether this instance should run the next tick."""
+        ...
 
 
 class ThreadedScheduler:
@@ -44,12 +71,17 @@ class ThreadedScheduler:
 
     Args:
         thread_name (str): OS thread name for the daemon (aids debugging / logs).
+        leader_gate (LeaderGate | None): Optional fleet-coordination gate
+            consulted before each tick. Defaults to None (always tick).
     """
 
-    def __init__(self, *, thread_name: str) -> None:
+    def __init__(
+        self, *, thread_name: str, leader_gate: LeaderGate | None = None
+    ) -> None:
         self._thread_name = thread_name
         self._stop_event = threading.Event()
         self._thread: threading.Thread | None = None
+        self._leader_gate = leader_gate
 
     def start(self) -> None:
         """Start the daemon thread, unless it is gated off or already running.
@@ -125,8 +157,37 @@ class ThreadedScheduler:
         """
         raise NotImplementedError
 
+    def _elected_interval(self) -> float:
+        """Run one gated iteration; return the seconds to wait before the next.
+
+        ``None`` gate -> tick (today's behavior). Gate ``True`` -> tick.
+        Gate ``False`` -> skip and wait the fixed follower poll.
+
+        The gate contract says ``should_run`` never raises (see
+        :class:`LeaderGate`), but this has zero defense of its own: an escaped
+        exception here would kill the daemon thread permanently and silently.
+        A raise is therefore caught defensively and treated as fail-open (tick
+        runs; duplicate work is safe, silence is not) rather than propagated.
+
+        Returns:
+            float: Seconds to wait before the next loop iteration.
+        """
+        if self._leader_gate is None:
+            return self._run_once()
+        try:
+            should_run = self._leader_gate.should_run()
+        except Exception:
+            logger.exception(
+                "event=%s_leader_gate_error — failing open", self._thread_name
+            )
+            return self._run_once()
+        if should_run:
+            return self._run_once()
+        logger.debug("event=%s_skip_not_leader", self._thread_name)
+        return _FOLLOWER_POLL_SECONDS
+
     def _run_loop(self) -> None:
-        """Drive :meth:`_run_once` until stopped, waiting its returned interval."""
+        """Drive gated iterations until stopped, waiting each returned interval."""
         while not self._stop_event.is_set():
-            interval = self._run_once()
+            interval = self._elected_interval()
             self._stop_event.wait(interval)

package/plugin/vendor/reflexio/reflexio/server/services/README.md

@@ -22,7 +22,7 @@ strings before deleting old import paths in the same PR.
 
 | File | Purpose |
 |------|---------|
-| `generation_service.py` | `GenerationService` — saves interactions, runs profile + playbook generation in parallel (ThreadPoolExecutor), schedules deferred evaluation when `session_id` is present. |
+| `generation_service.py` | `GenerationService` — saves interactions, runs/defer-runs profile + playbook generation, schedules deferred evaluation when `session_id` is present, exposes `run_deferred_learning()` for the non-durable publish worker, and the durable `compute_deferred_learning()` → `persist_deferred_learning()` → `emit_deferred_learning_side_effects()` split (compute outside any scope; only persist + fence inside `commit_scope()`). |
 | `publish_learning_worker.py` | Deferred post-persist publish learning worker — queues async publish learning after durable interaction writes and requeues under publish limiter pressure. |
 | `base_generation_service.py` + `base_generation/` | `BaseGenerationService` stable import surface plus mixins for batch progress, config filtering, extraction lifecycle, should-run prechecks, status transitions, and usage billing. Per-extractor timeout `EXTRACTOR_TIMEOUT_SECONDS = 300`. |
 | `operation_state_utils.py` | `OperationStateManager` — all `_operation_state` access (progress, concurrency locks, extractor/aggregator bookmarks, cluster fingerprints, cancellation). |
@@ -38,10 +38,11 @@ strings before deleting old import paths in the same PR.
 | `agent_success_evaluation/` | `AgentSuccessEvaluationService` | `service.py` (session-level service), `runner.py` (`run_group_evaluation`), `scheduler.py` (`GroupEvaluationScheduler`, 10-min defer), `regen_jobs.py`, `components/evaluator.py` |
 | `reflection/` | `ReflectionService` | `service.py`, `components/extractor.py` — post-horizon reflection; runs **before** extraction so extractors read post-reflection state |
 
-## Async Extraction
+## Durable and Async Extraction
 
 | Directory | Purpose |
 |-----------|---------|
+| `durable_learning/` | Durable `learning_jobs` scheduler + worker. Gated by `REFLEXIO_DURABLE_LEARNING_QUEUE`; discovers orgs with pending work, claims jobs with leases, then per job runs `compute_deferred_learning()` **outside** any writer transaction, applies `persist_deferred_learning()` + fenced `complete_learning_job()` inside a short `storage.commit_scope()`, and fires `emit_deferred_learning_side_effects()` post-commit — fenced completion guarantees exactly-once side effects. |
 | `extraction/` | Shared async extraction runtime: `resumable_agent.py`, `resume_scheduler.py`, `resume_worker.py`, `pending_tool_call_dispatch.py` (`ask_human`), `prior_answer_search.py`, `agent_run_records.py`, and `outcome.py`. Long-horizon / tool-mediated extraction continues outside the request path. See [README](extraction/README.md). |
 
 ## Evaluation, Search & Integrations
@@ -57,13 +58,13 @@ strings before deleting old import paths in the same PR.
 | `pre_retrieval/` | `QueryReformulator` (`_query_reformulator.py`) + `DocumentExpander` (`_document_expander.py`) - query rewrite and doc expansion for recall. Compact by design; see [README](pre_retrieval/README.md). |
 | `tagging/` | `TaggingService` (`service.py`) + deferred `tagging_scheduler.py` - post-generation profile/playbook tagging. Compact by design; see [README](tagging/README.md). |
 | `unified_search_service.py` | `run_unified_search()` — two-phase parallel search across profiles / agent playbooks / user playbooks. |
-| `retrieval/` | `relevance_floor.py` — result relevance thresholding. |
+| `retrieval/` | `relevance_floor.py` — result relevance thresholding. `temporal.py` — temporal post-processing driven by reformulation signals: query time windows → per-arm SQL filters, near-duplicate freshness collapse for current-value questions, timestamp ordering for latest-value questions. (Superseded/expired rows are already excluded by storage search SQL.) |
 
 ## Persistence & Config
 
 | Path | Purpose |
 |------|---------|
-| `storage/` | `storage_base/` and `sqlite_storage/` keep legacy domain facades while focused subpackages own `profiles/`, `playbook/`, `agent_run/`, `governance/`, and SQLite `base/` helpers; plus `governance_validation.py` and `retention*.py`. Access via `request_context.storage` only. |
+| `storage/` | `storage_base/` and `sqlite_storage/` keep legacy domain facades while focused subpackages own `profiles/`, `playbook/`, `agent_run/`, `governance/`, durable `learning_jobs`, and SQLite `base/` helpers; plus `governance_validation.py` and `retention*.py`. Access via `request_context.storage` only. |
 | `configurator/` | `DefaultConfigurator` — loads YAML config and creates the storage backend. |
 
 ## Key Rules
@@ -72,5 +73,6 @@ strings before deleting old import paths in the same PR.
 - **NEVER import storage implementations directly** — use `request_context.storage` (`BaseStorage`).
 - **ALWAYS use `LiteLLMClient`** for completions/embeddings and `request_context.prompt_manager.render_prompt(...)` for prompts — no hardcoded prompts, no direct OpenAI/Claude clients.
 - **All `_operation_state` writes go through `OperationStateManager`** — don't touch the table directly (it backs locks, bookmarks, progress, and cancellation).
+- **All durable queue claims go through `LearningJobStoreABC`** — do not update `learning_jobs` directly; completion is fenced by `claim_token` and must roll back the surrounding `commit_scope` when superseded.
 - **`tool_can_use` lives at root `Config`** — shared by playbook extraction and success evaluation, not per-service.
 - **Preserve governance subject refs/barriers** — route validation through `services/governance/` and `storage/governance_validation.py`; do not bypass retention or subject-write checks in storage implementations.

package/plugin/vendor/reflexio/reflexio/server/services/agent_success_evaluation/README.md

@@ -5,9 +5,10 @@ Session-level agent success evaluation module.
 ## Module Shape
 
 - `service.py`: `AgentSuccessEvaluationService`, the request-path service that runs configured evaluators and saves result rows.
-- `runner.py`: `run_group_evaluation(...)`, the background/manual workflow entry point that loads a session, runs the service, dispatches shadow comparison, and marks operation state.
+- `runner.py`: `run_group_evaluation(...)`, the background/manual workflow entry point that loads a session, runs the service, and marks operation state. After agent-success work it also runs the retrieved-learning evaluation (independent completion; generation + session-fingerprint fenced) and returns a `GroupEvaluationOutcome` carrying both statuses.
 - `scheduler.py`: `GroupEvaluationScheduler`, the deferred inactivity scheduler.
 - `components/evaluator.py`: `AgentSuccessEvaluator`, the LLM evaluator component.
+- `components/retrieved_learning_evaluator.py`: `RetrievedLearningEvaluator`, per-learning relevance/impact judges over `Interaction.retrieved_learnings`; results go to the `retrieved_learning_evaluation` table.
 - `regen_jobs.py`: regeneration job planning and execution; remains root-level because API/admin regenerate flows import it directly.
 - `_eval_health.py`: producer/scheduler health counters.
 - `agent_success_evaluation_constants.py`: prompt/model output constants.
@@ -15,7 +16,7 @@ Session-level agent success evaluation module.
 
 ## Prompt IDs
 
-- Owns `agent_success_evaluation`.
+- Owns `agent_success_evaluation`, `retrieved_learning_relevance`, and `retrieved_learning_impact`.
 - Keeps historical/configured prompt ID `agent_success_evaluation_with_comparison` stable where prompt mapping tests require it.
 
 Do not reintroduce the deleted service/evaluator/runner/scheduler legacy

package/plugin/vendor/reflexio/reflexio/server/services/agent_success_evaluation/_eval_health.py

@@ -51,6 +51,34 @@ class EvalHealth:
         self._skip_counts: Counter[SkipReason] = Counter()
         self._failures: deque[float] = deque()
         self._last_tick_monotonic: float | None = None
+        self._retrieved_outcome_counts: Counter[str] = Counter()
+        self._retrieved_invalid_ref_count = 0
+        self._retrieved_failed_relevance_chunks = 0
+        self._retrieved_failed_impact_chunks = 0
+
+    def record_retrieved_outcome(
+        self, status: str, *, diagnostics: dict[str, Any] | None = None
+    ) -> None:
+        """Record one retrieved-learning evaluation outcome.
+
+        Args:
+            status (str): Final invocation status (complete/degraded/failed/
+                not_applicable/...).
+            diagnostics (dict, optional): Evaluator diagnostics; the
+                invalid-ref and failed-chunk counters are accumulated from it.
+        """
+        with self._lock:
+            self._retrieved_outcome_counts[status] += 1
+            if diagnostics:
+                self._retrieved_invalid_ref_count += int(
+                    diagnostics.get("invalid_ref_count") or 0
+                )
+                self._retrieved_failed_relevance_chunks += int(
+                    diagnostics.get("failed_relevance_chunks") or 0
+                )
+                self._retrieved_failed_impact_chunks += int(
+                    diagnostics.get("failed_impact_chunks") or 0
+                )
 
     def record_skip(self, reason: SkipReason) -> None:
         """Bump the counter for `reason` by one.
@@ -99,6 +127,12 @@ class EvalHealth:
                 "skip_counts": {r.value: self._skip_counts[r] for r in SkipReason},
                 "producer_failures_24h": len(self._failures),
                 "last_tick_monotonic": self._last_tick_monotonic,
+                "retrieved_learning": {
+                    "outcome_counts": dict(self._retrieved_outcome_counts),
+                    "invalid_ref_count": self._retrieved_invalid_ref_count,
+                    "failed_relevance_chunks": self._retrieved_failed_relevance_chunks,
+                    "failed_impact_chunks": self._retrieved_failed_impact_chunks,
+                },
             }
 
     def _trim_locked(self, now_ts: float) -> None:
@@ -116,6 +150,13 @@ def record_skip(reason: SkipReason) -> None:
     _HEALTH.record_skip(reason)
 
 
+def record_retrieved_outcome(
+    status: str, *, diagnostics: dict[str, Any] | None = None
+) -> None:
+    """Module-level proxy to the singleton."""
+    _HEALTH.record_retrieved_outcome(status, diagnostics=diagnostics)
+
+
 def record_producer_failure(at_ts: float | None = None) -> None:
     """Module-level proxy to the singleton."""
     _HEALTH.record_producer_failure(at_ts=at_ts)