claude-smart 0.2.49 → 0.2.50

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

@@ -17,6 +17,7 @@ Description: FastAPI backend server that processes user interactions to generate
   - [Profile Generation](#profile-generation)
   - [Playbook Extraction](#playbook-extraction)
   - [Agent Success Evaluation](#agent-success-evaluation)
+  - [Durable Learning Queue](#durable-learning-queue)
   - [Reflection and Async Extraction](#reflection-and-async-extraction)
   - [Shadow Comparison and Evaluation Overview](#shadow-comparison-and-evaluation-overview)
   - [Playbook Optimizer and Braintrust](#playbook-optimizer-and-braintrust)
@@ -38,6 +39,7 @@ Description: FastAPI backend server that processes user interactions to generate
 - **Endpoint Helpers**: `api_endpoints/` - Shared handlers/helpers plus `RequestContext` used by route modules
 - **Extension Registry**: `extensions.py` - Capability and service registry for optional OSS/enterprise integrations
 - **Core Service**: `services/generation_service.py` - Main orchestrator
+- **Durable Learning**: `services/durable_learning/` - background queue worker for deferred post-publish extraction
 
 ## Cache
 
@@ -86,7 +88,7 @@ Description: FastAPI backend server that processes user interactions to generate
 - **Health/version**: `GET /`, `GET /health`, `GET /healthz`, `GET /healthz/eval`, `GET /meta/version`
 - **Identity/config**: `GET /api/whoami`, `GET /api/my_config`, `GET /api/get_config`, `POST /api/set_config`, `POST /api/update_config`
 - **Publish/direct writes**: `POST /api/publish_interaction`, `POST /api/add_user_profile`, `POST /api/add_user_playbook`, `POST /api/add_agent_playbook`
-- **Retrieval**: `POST /api/get_requests`, `POST /api/get_interactions`, `GET /api/get_all_interactions`, `POST /api/get_profiles`, `GET /api/get_all_profiles`, `POST /api/get_user_playbooks`, `POST /api/get_agent_playbooks`, `POST /api/get_agent_success_evaluation_results`
+- **Retrieval**: `POST /api/get_requests`, `POST /api/get_interactions`, `GET /api/get_all_interactions`, `GET /api/learning_status`, `POST /api/get_profiles`, `GET /api/get_all_profiles`, `POST /api/get_user_playbooks`, `POST /api/get_agent_playbooks`, `POST /api/get_agent_success_evaluation_results`, `POST /api/get_retrieved_learning_evaluation_results`
 - **Search/stats**: `POST /api/search`, `POST /api/search_profiles`, `POST /api/rerank_user_profiles`, `POST /api/search_interactions`, `POST /api/search_user_playbooks`, `POST /api/search_agent_playbooks`, `GET /api/storage_stats`, `GET /api/get_profile_statistics`, `POST /api/get_dashboard_stats`, `POST /api/get_playbook_application_stats`
 - **Profile lifecycle**: `POST /api/rerun_profile_generation`, `POST /api/manual_profile_generation`, `POST /api/upgrade_all_profiles`, `POST /api/downgrade_all_profiles`, `GET /api/profile_change_log`, `PUT /api/update_user_profile`, `DELETE /api/delete_profile`, `DELETE /api/delete_profiles_by_ids`, `DELETE /api/delete_all_profiles`
 - **Playbook lifecycle**: `POST /api/rerun_playbook_generation`, `POST /api/manual_playbook_generation`, `POST /api/run_playbook_aggregation`, `GET /api/playbook_aggregation_change_logs`, `POST /api/upgrade_all_user_playbooks`, `POST /api/downgrade_all_user_playbooks`, `PUT /api/update_agent_playbook_status`, `PUT /api/update_agent_playbook`, `PUT /api/update_user_playbook`, `DELETE /api/delete_agent_playbook`, `DELETE /api/delete_user_playbook`, `DELETE /api/delete_agent_playbooks_by_ids`, `DELETE /api/delete_user_playbooks_by_ids`, `DELETE /api/delete_all_playbooks`, `DELETE /api/delete_all_user_playbooks`, `DELETE /api/delete_all_agent_playbooks`
@@ -210,12 +212,14 @@ python -m reflexio.server.scripts.manage_invitation_codes list --show-used
 - **Profile memory**: `profile/` extracts, deduplicates, and applies user profile updates.
 - **Playbook memory**: `playbook/` extracts user playbooks, consolidates them against existing rows, aggregates them into agent playbooks, and tracks aggregation change logs.
 - **Evaluation**: `agent_success_evaluation/service.py`, `agent_success_evaluation/runner.py`, `agent_success_evaluation/scheduler.py`, `agent_success_evaluation/components/evaluator.py`, `shadow_comparison/`, and `evaluation_overview/` handle session grading, per-turn shadow verdicts, regeneration jobs, and dashboard-facing rollups.
+- **Durable learning queue**: `durable_learning/scheduler.py` and `durable_learning/worker.py` drain `learning_jobs` after deferred publishes and report coverage through `GET /api/learning_status`.
 - **Async clarification**: `extraction/` and `reflection/` manage resumable agent runs, pending tool calls, prior-answer search, and long-horizon reflection updates.
 - **Search preparation**: `pre_retrieval/` and `unified_search_service.py` handle query reformulation, document expansion, embeddings, and cross-entity search orchestration.
 - **Optimization/integrations**: `playbook_optimizer/` and `braintrust/` run candidate playbook optimization, rollout support, and Braintrust export/sync.
 - **Lineage**: `lineage/` resolves active records across superseded chains and schedules tombstone garbage collection for profile/playbook storage.
 - **Governance**: `governance/` defines subject-reference contracts and retention/barrier policy helpers used by storage and lineage paths.
 - **Persistence/config**: `storage/`, `configurator/`, and `operation_state_utils.py` provide storage abstractions, config loading, locks, bookmarks, progress, and cancellation.
+- **Usage metering**: `billing_meter.py` converts learning/search signals into optional `usage_events` without importing enterprise types.
 
 ### Orchestrator
 
@@ -415,7 +419,9 @@ Key files:
 - `agent_success_evaluation_constants.py`: Output schema (`AgentSuccessEvaluationOutput`)
 - `agent_success_evaluation_utils.py`: Message construction utilities
 - `scheduler.py`: `GroupEvaluationScheduler` singleton - min-heap priority queue with daemon thread, defers evaluation until 10 min after last request in session
-- `runner.py`: `run_group_evaluation()` - fetches all requests/interactions for a session, builds `RequestInteractionDataModel` list, runs `service.py`
+- `runner.py`: `run_group_evaluation()` - fetches all requests/interactions for a session, builds `RequestInteractionDataModel` list, runs `service.py`, then the retrieved-learning phase; returns `GroupEvaluationOutcome` (per-family statuses)
+- `components/retrieved_learning_evaluator.py`: `RetrievedLearningEvaluator` - per-learning relevance/impact judges over `Interaction.retrieved_learnings`; results replace the session's `retrieved_learning_evaluation` snapshot atomically (generation + session-fingerprint fenced, see `services/storage/storage_base/retrieved_learning_state.py`)
+- `services/storage/storage_base/evaluation_state_keys.py`: single source of truth for the three evaluation `_operation_state` key formats (agent-success marker, grade-on-demand cache, retrieved-learning state) shared by producers and governance erasure
 
 **Flow**: Interactions → `agent_success_evaluation/scheduler.py` → `agent_success_evaluation/runner.py` → `agent_success_evaluation/service.py` → `agent_success_evaluation/components/evaluator.py` → `AgentSuccessEvaluationResult` → Storage
 
@@ -423,7 +429,18 @@ Key files:
 
 **Tool Context**: Reads `tool_can_use` from root `Config` level (shared with playbook extraction).
 
-**Shadow Comparison**: Session-level shadow comparison was retracted in F1 because multi-turn shadow content suffers from trajectory contamination (turn 2+ user messages react to the regular response, not the shadow). The `regular_vs_shadow` field on `AgentSuccessEvaluationResult` is preserved as a nullable historical column but is always `None` on newly produced rows. Per-turn shadow comparison lives in a dedicated `services/shadow_comparison/` judge that writes its verdicts to a separate table — see the F1 spec.
+**Shadow Comparison**: Session-level shadow comparison was retracted in F1 because multi-turn shadow content suffers from trajectory contamination (turn 2+ user messages react to the regular response, not the shadow). The `regular_vs_shadow` field on `AgentSuccessEvaluationResult` is preserved as a nullable historical column but is always `None` on newly produced rows. Per-turn shadow comparison is scheduled from the publish path whenever an assistant interaction carries `shadow_content`; it lives in a dedicated `services/shadow_comparison/` judge that writes verdicts to a separate table, independent of session-level evaluation sampling.
+
+### Durable Learning Queue
+
+**Directory**: `services/durable_learning/`
+
+Key files:
+- `scheduler.py`: `DurableLearningScheduler` plus `maybe_start_durable_learning()`; starts only when `REFLEXIO_DURABLE_LEARNING_QUEUE` is truthy and polls orgs with actionable queue rows.
+- `worker.py`: `DurableLearningWorker`; claims leased jobs, reloads the persisted request, then splits each job into `compute_deferred_learning()` (LLM extraction + dedup + embeddings, **no** writer transaction held) → `persist_deferred_learning()` + fenced `complete_learning_job()` inside one short `storage.commit_scope()` → `emit_deferred_learning_side_effects()` post-commit (billing / telemetry / tagging / lock release).
+- `services/storage/storage_base/_learning_jobs.py`: `LearningJobStoreABC`, queue status types, coverage-based request status, and the direct-storage contract implemented by each backend.
+
+**Pattern**: `POST /api/publish_interaction` returns immediately when `wait_for_response=false`; callers use the returned `request_id` with `GET /api/learning_status`. Queue workers run the LLM compute **outside** any writer transaction; only the persist half + the fenced `complete_learning_job()` run inside `storage.commit_scope()`, and must raise/rollback if `complete_learning_job()` returns 0 because another worker stole the lease.
 
 ### Reflection and Async Extraction
 
@@ -444,7 +461,8 @@ Key files:
 **Directories**: `services/shadow_comparison/`, `services/evaluation_overview/`
 
 Key files:
-- `shadow_comparison/judge.py`: Per-turn regular-vs-shadow judge that writes shadow verdicts through storage
+- `shadow_comparison/judge.py`: Per-turn regular-vs-shadow judge
+- `shadow_comparison/dispatcher.py` and `shadow_comparison/worker.py`: Publish-time dispatch and bounded background execution for shadow verdict writes
 - `shadow_comparison/outcome.py`: Verdict outcome model helpers
 - `evaluation_overview/service.py`: Aggregates evaluation-page metrics
 - `evaluation_overview/components/hero_state.py`, `evaluation_overview/components/distribution.py`, `evaluation_overview/components/rule_attribution.py`, `evaluation_overview/components/shadow_aggregation.py`: Focused aggregation helpers

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

@@ -230,13 +230,16 @@ if DEBUG_LOG_TO_CONSOLE:
         logging.ERROR
     )
 else:
-    # Production (DEBUG_LOG_TO_CONSOLE off): emit INFO+ app logs to stdout so the
-    # container log driver (e.g. CloudWatch awslogs) captures business-logic audit
-    # lines — billing/webhook/enforcement, etc. Without an explicit handler the
-    # stdlib "handler of last resort" emits only WARNING+ to stderr, so INFO logs
-    # were silently dropped in production. Plain formatter (no colors/files/dedup)
-    # keeps this lean and log-driver friendly — none of the DEBUG-branch overhead.
-    root_logger.setLevel(logging.INFO)
+    # Production (DEBUG_LOG_TO_CONSOLE off): default the root logger to WARNING.
+    # App-wide INFO on a busy server drove ~3x log volume and grew memory to the
+    # container ceiling over a few hours (prod incident 2026-07-04) — so INFO is
+    # OPT-IN per subsystem, not global. A stdout StreamHandler is still attached at
+    # INFO so that any logger explicitly raised to INFO reaches the container log
+    # driver (e.g. CloudWatch awslogs); everything else stays WARNING+ and cheap.
+    #
+    # REFLEXIO_INFO_LOGGERS: comma-separated logger-name prefixes to surface at INFO
+    # (e.g. the billing money-path). Empty/unset => WARNING-only (the safe default).
+    root_logger.setLevel(logging.WARNING)
     if not any(isinstance(h, logging.StreamHandler) for h in root_logger.handlers):
         prod_console_handler = logging.StreamHandler(sys.stdout)
         prod_console_handler.setLevel(logging.INFO)
@@ -245,7 +248,14 @@ else:
         )
         root_logger.addHandler(prod_console_handler)
 
-    # Keep noisy loggers quiet even at INFO (mirror the debug branch's suppression).
+    for _info_logger in (
+        name.strip()
+        for name in os.getenv("REFLEXIO_INFO_LOGGERS", "").split(",")
+        if name.strip()
+    ):
+        logging.getLogger(_info_logger).setLevel(logging.INFO)
+
+    # Keep noisy loggers quiet regardless of the above (mirror the debug branch).
     for _noisy in ("litellm", "LiteLLM", "httpx", "httpcore", "openai", "urllib3"):
         logging.getLogger(_noisy).setLevel(logging.WARNING)
     logging.getLogger("reflexio.server.site_var.site_var_manager").setLevel(

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

@@ -15,6 +15,7 @@ Flags mirror the subset of ``uvicorn`` CLI options that
 from __future__ import annotations
 
 import argparse
+import os
 import sys
 
 import uvicorn
@@ -100,6 +101,11 @@ def main(argv: list[str] | None = None) -> None:
         )
         raise SystemExit(2)
 
+    # Record the configured worker count so per-worker startup guards can read
+    # it (uvicorn exposes no worker-count env inside a worker process). See
+    # ``embedder_warmup._detected_worker_count``.
+    os.environ["REFLEXIO_SERVER_WORKERS"] = str(1 if args.reload else args.workers)
+
     if args.reload:
         uvicorn.run(
             args.app,

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

@@ -16,7 +16,7 @@ iterates (e.g. the QPS billable-endpoint scan over ``core_router.routes``).
 
 import inspect
 import logging
-from collections.abc import Callable
+from collections.abc import Callable, Iterable
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -77,6 +77,34 @@ __all__ = [
     "limiter",
 ]
 
+
+def _log_multi_worker_daemons() -> None:
+    """Warn once at startup when multiple worker processes will run daemons.
+
+    ``--workers N`` (N>1) runs the full daemon set in every worker process
+    (duplicate ticking). Safe by the concurrent-tick invariant — every daemon
+    tick is concurrent-safe — but worth one visible line (design D3).
+
+    Reuses ``embedder_warmup._detected_worker_count`` (checks
+    ``REFLEXIO_SERVER_WORKERS`` then falls back to ``WEB_CONCURRENCY``)
+    instead of re-implementing a narrower env read here. When the count is
+    undetectable (``None``), this logs nothing — it cannot verify the count,
+    so it must not assume a single worker.
+    """
+    from reflexio.server.llm.providers.embedder_warmup import (
+        _detected_worker_count,
+    )
+
+    workers = _detected_worker_count()
+    if workers is not None and workers > 1:
+        logger.warning(
+            "event=multi_worker_daemons workers=%d — background daemons tick in "
+            "every worker process (duplicate ticking; safe: ticks are "
+            "concurrent-safe by design)",
+            workers,
+        )
+
+
 # ``core_router`` stays an aggregator: it ``include_router``s every domain
 # sub-router so ``core_router.routes`` still enumerates all data-plane handlers
 # (enterprise QPS enforcement iterates this list). The include order is
@@ -269,6 +297,7 @@ def create_app(
     capabilities: "CapabilityRegistry | None" = None,
     app_context_factory: "Callable[[], AppContext] | None" = None,
     profile: "DeploymentProfile | None" = None,
+    durable_org_ids_provider: Callable[[], Iterable[str]] | None = None,
 ) -> FastAPI:
     """Factory to create a FastAPI app.
 
@@ -310,6 +339,16 @@ def create_app(
             provided it is the single source for router-group mounting, auth, and
             data-plane lifespan gating (the legacy knobs still populate the derived
             profile, so callers may pass either — they express the same thing).
+        durable_org_ids_provider: Optional zero-arg callable returning the org_ids
+            with actionable durable-learning work, threaded straight through to
+            ``maybe_start_durable_learning(org_ids_provider=...)``. When None
+            (default) the single-ref bootstrap default is used, so behaviour is
+            byte-identical to before this parameter existed. It is a plain
+            injectable seam so a deployment (e.g. enterprise cross-ref fan-out) can
+            supply its own discovery WITHOUT this factory importing deployment
+            logic. It is only consulted when ``REFLEXIO_DURABLE_LEARNING_QUEUE`` is
+            on — when the flag is off ``maybe_start_durable_learning`` returns None
+            without ever calling the provider.
 
     Returns:
         Configured FastAPI application.
@@ -354,6 +393,9 @@ def create_app(
     from reflexio.server.services.lineage.gc_scheduler import (
         maybe_start_lineage_gc,
     )
+    from reflexio.server.services.lineage.vector_backfill_sweep import (
+        install_missing_vector_backfill_sweep,
+    )
 
     @asynccontextmanager
     async def lifespan(app: FastAPI) -> AsyncIterator[None]:  # noqa: ARG001
@@ -361,7 +403,21 @@ def create_app(
         gc_scheduler = None
         durable_learning_scheduler = None
         started_caps: list = []
+        # D8 config guards + D5 warm-before-ready. Both are dormant unless the
+        # deployment has flipped to the in-process local embedder
+        # (REFLEXIO_EMBEDDING_PROVIDER=inprocess + local/* default); pre-flip
+        # this is a no-op and /health stays byte-for-byte unchanged. Run before
+        # the data-plane block so a gated deployment warms regardless of the
+        # mount profile (otherwise /health could 503 forever).
+        from reflexio.server.llm.providers.embedder_warmup import (
+            maybe_start_embedder_warmup,
+            run_startup_config_guards,
+        )
+
+        run_startup_config_guards()
+        maybe_start_embedder_warmup()
         if mounts_data_plane:
+            _log_multi_worker_daemons()
             log_publish_hardware_capacity()
             validate_llm_availability()
             from reflexio.server.llm.rerank import prewarm as _prewarm_cross_encoder
@@ -376,17 +432,24 @@ def create_app(
                 lambda org_id: RequestContext(org_id=org_id),
                 bootstrap_org_id=bootstrap_org_id,
             )
+            # Register the missing-vector backfill sweep (opt-in via
+            # REFLEXIO_MISSING_VECTOR_BACKFILL_ENABLED) BEFORE starting the GC
+            # scheduler, so its per-org hook is visible when maybe_start_lineage_gc
+            # evaluates its start conditions. No-op when the flag is off.
+            install_missing_vector_backfill_sweep()
             gc_scheduler = maybe_start_lineage_gc(
                 lambda org_id: RequestContext(org_id=org_id),
                 bootstrap_org_id=bootstrap_org_id,
             )
             # Durable learning drains the learning_jobs queue per org. Gated on
             # REFLEXIO_DURABLE_LEARNING_QUEUE; the default provider discovers
-            # orgs-with-work via the bootstrap storage (single-ref). Enterprise
-            # cross-ref fan-out is a deferred follow-up.
+            # orgs-with-work via the bootstrap storage (single-ref). A deployment
+            # may inject its own discovery via ``durable_org_ids_provider`` (e.g.
+            # enterprise cross-ref fan-out); when None the single-ref default runs.
             durable_learning_scheduler = maybe_start_durable_learning(
                 lambda org_id: RequestContext(org_id=org_id),
                 bootstrap_org_id=bootstrap_org_id,
+                org_ids_provider=durable_org_ids_provider,
             )
         try:
             if capabilities is not None:

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

@@ -8,8 +8,15 @@ wrapper over the ``record_usage_event`` hook (which only enqueues). No DB I/O.
 
 from __future__ import annotations
 
+import logging
+import uuid
+from collections.abc import Mapping
+from typing import Any
+
 from reflexio.server.usage_metrics import record_usage_event
 
+logger = logging.getLogger(__name__)
+
 _INTERNAL = (
     "internal"  # == BillingCallerType.INTERNAL.value (kept literal; OSS stays clean)
 )
@@ -29,7 +36,10 @@ def record_extraction_tokens(
 ) -> None:
     """Emit the Learning cost facet — call only when extraction fired.
 
-    No-op when ``billing_input_tokens <= 0``.
+    No-op when ``billing_input_tokens <= 0``. Each call mints a fresh
+    ``event_key=f"tok:{uuid4()}"`` so two token emits under the same
+    ``request_id`` (e.g. profile + playbook extraction in one request) never
+    collapse into one billed event downstream.
 
     Args:
         org_id: Organisation identifier.
@@ -51,6 +61,7 @@ def record_extraction_tokens(
         pipeline=pipeline,
         request_id=request_id,
         session_id=session_id,
+        event_key=f"tok:{uuid.uuid4()}",
         count_value=billing_input_tokens,
         prompt_tokens=prompt_tokens,
         completion_tokens=completion_tokens,
@@ -68,12 +79,26 @@ def record_learnings_generated(
     platform_llm: bool | None,
     platform_storage: bool | None,
     pipeline: str | None = None,
+    user_id: str | None = None,
     request_id: str | None = None,
     session_id: str | None = None,
+    source: str | None = None,
+    agent_version: str | None = None,
+    playbook_name: str | None = None,
+    entity_type: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
 ) -> None:
     """Emit the Learning value facet — number of profiles/playbooks generated.
 
-    No-op when ``count <= 0``.
+    Documented FALLBACK for callers that genuinely lack a per-record id list
+    (e.g. dedup/consolidation can reduce the persisted count below the raw
+    extracted count, so there is no safe 1:1 id per unit of ``count``). Prefer
+    :func:`record_learnings_generated_records` whenever the caller has the
+    durable learning ids in scope. No-op when ``count <= 0``.
+
+    Emits a single event carrying a synthesized ``event_key=f"learn-batch:{uuid4()}"``
+    (distinct per call) so this aggregate event still has a dedup key, even
+    though it is not entity-backed.
 
     Args:
         org_id: Organisation identifier.
@@ -81,8 +106,14 @@ def record_learnings_generated(
         platform_llm: True iff the platform supplies the LLM for this org.
         platform_storage: True iff the platform supplies storage; None defers to rollup.
         pipeline: Optional pipeline tag (e.g. ``"playbook"``).
+        user_id: Optional user ID tied to the generated learning.
         request_id: Optional request correlation ID.
         session_id: Optional session ID.
+        source: Optional metering source/path label.
+        agent_version: Optional agent version tied to the generated learning.
+        playbook_name: Optional playbook name for playbook learnings.
+        entity_type: Optional entity type (e.g. ``"profile"``).
+        metadata: Optional path-specific usage metadata.
     """
     if count <= 0:
         return
@@ -91,15 +122,237 @@ def record_learnings_generated(
         event_name="learnings_generated",
         event_category="learning",
         pipeline=pipeline,
+        user_id=user_id,
         request_id=request_id,
         session_id=session_id,
+        source=source,
+        agent_version=agent_version,
+        playbook_name=playbook_name,
+        entity_type=entity_type,
+        event_key=f"learn-batch:{uuid.uuid4()}",
         count_value=count,
         platform_llm=platform_llm,
         platform_storage=platform_storage,
         caller_type=_INTERNAL,
+        metadata=metadata,
     )
 
 
+def record_learnings_generated_records(
+    *,
+    org_id: str,
+    learning_ids: list[str],
+    platform_llm: bool | None,
+    platform_storage: bool | None,
+    pipeline: str | None = None,
+    user_id: str | None = None,
+    request_id: str | None = None,
+    session_id: str | None = None,
+    source: str | None = None,
+    agent_version: str | None = None,
+    playbook_name: str | None = None,
+    entity_type: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> None:
+    """Emit the Learning value facet — one event per generated learning record.
+
+    Entity-backed alternative to :func:`record_learnings_generated`: emits one
+    ``learnings_generated`` event per id in ``learning_ids`` (``count_value=1``,
+    ``event_key=f"learn:{entity_type}:{id}"``, ``entity_id=id``) instead of a
+    single aggregate event, so downstream dedup can key on the learning id.
+    The ``entity_type`` segment is required for collision-freedom: entity-backed
+    callers draw ids from separate autoincrement primary keys in separate
+    tables (e.g. ``user_playbook_id`` and ``agent_playbook_id`` both start at
+    1), so the same integer id can legitimately occur in two tables — without
+    the entity-type segment those would mint the same ``event_key`` and
+    collapse into one event downstream. When ``entity_type`` is falsy, a
+    stable ``"_"`` placeholder is used (``learn:_:{id}``) rather than emitting
+    ``entity_type=None`` literally into the key. The summed ``count_value``
+    across the emitted events equals ``len(learning_ids)`` — unchanged from
+    the total a caller would have passed as ``count`` to
+    :func:`record_learnings_generated`.
+
+    Callers must pass real, durable ids — never fabricate one to pad the
+    list. No-op when ``learning_ids`` is empty.
+
+    Args:
+        org_id: Organisation identifier.
+        learning_ids: Ids of the learnings durably generated in this run
+            (e.g. ``profile_id`` / ``user_playbook_id`` / ``agent_playbook_id``).
+        platform_llm: True iff the platform supplies the LLM for this org.
+        platform_storage: True iff the platform supplies storage; None defers to rollup.
+        pipeline: Optional pipeline tag (e.g. ``"playbook"``).
+        user_id: Optional user ID tied to the generated learning.
+        request_id: Optional request correlation ID.
+        session_id: Optional session ID.
+        source: Optional metering source/path label.
+        agent_version: Optional agent version tied to the generated learning.
+        playbook_name: Optional playbook name for playbook learnings.
+        entity_type: Optional entity type (e.g. ``"profile"``).
+        metadata: Optional path-specific usage metadata (shared across events).
+    """
+    key_entity_type = entity_type or "_"
+    for learning_id in learning_ids:
+        record_usage_event(
+            org_id=org_id,
+            event_name="learnings_generated",
+            event_category="learning",
+            pipeline=pipeline,
+            user_id=user_id,
+            request_id=request_id,
+            session_id=session_id,
+            source=source,
+            agent_version=agent_version,
+            playbook_name=playbook_name,
+            entity_type=entity_type,
+            entity_id=learning_id,
+            event_key=f"learn:{key_entity_type}:{learning_id}",
+            count_value=1,
+            platform_llm=platform_llm,
+            platform_storage=platform_storage,
+            caller_type=_INTERNAL,
+            metadata=metadata,
+        )
+
+
+def emit_learnings_generated(
+    *,
+    org_id: str,
+    configurator: Any,
+    count: int,
+    source: str,
+    pipeline: str | None = None,
+    user_id: str | None = None,
+    request_id: str | None = None,
+    agent_version: str | None = None,
+    playbook_name: str | None = None,
+    entity_type: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> None:
+    """Resolve ``platform_llm`` from config and emit the Learning value facet.
+
+    Convenience wrapper for the non-extraction learning-mutation paths (reflection,
+    resumable-extraction finalization, aggregation, offline-tuner auto-apply). It
+    owns the ``configurator.get_config()`` + ``platform_llm_from_config`` lookup so
+    each call site stays a thin one-liner, and — critically — is **guarded**: the
+    product path must never fail because metering failed, so config resolution and
+    emission are wrapped and any exception is logged and swallowed (mirroring the
+    extraction path's ``_record_billing_learning_events``). No-op when
+    ``count <= 0``.
+
+    Args:
+        org_id: Organisation identifier.
+        configurator: Object exposing ``get_config()`` for platform-LLM resolution.
+        count: Number of learnings durably produced by this path.
+        source: Metering source/path label (e.g. ``"reflection"``).
+        pipeline: Optional pipeline tag (e.g. ``"playbook"``).
+        user_id: Optional user ID tied to the generated learning.
+        request_id: Optional request correlation ID.
+        agent_version: Optional agent version tied to the generated learning.
+        playbook_name: Optional playbook name for playbook learnings.
+        entity_type: Optional entity type (e.g. ``"profile"``).
+        metadata: Optional path-specific usage metadata.
+    """
+    if count <= 0:
+        return
+    try:
+        from reflexio.server.billing_signals import platform_llm_from_config
+
+        config = configurator.get_config()
+        record_learnings_generated(
+            org_id=org_id,
+            count=count,
+            platform_llm=platform_llm_from_config(config),
+            platform_storage=None,
+            pipeline=pipeline,
+            user_id=user_id,
+            request_id=request_id,
+            source=source,
+            agent_version=agent_version,
+            playbook_name=playbook_name,
+            entity_type=entity_type,
+            metadata=metadata,
+        )
+    except Exception:
+        logger.warning(
+            "emit_learnings_generated failed for source=%s org=%s; "
+            "learnings_generated event not emitted",
+            source,
+            org_id,
+            exc_info=True,
+        )
+
+
+def emit_learnings_generated_records(
+    *,
+    org_id: str,
+    configurator: Any,
+    learning_ids: list[str],
+    source: str,
+    pipeline: str | None = None,
+    user_id: str | None = None,
+    request_id: str | None = None,
+    agent_version: str | None = None,
+    playbook_name: str | None = None,
+    entity_type: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> None:
+    """Resolve ``platform_llm`` from config and emit one event per learning id.
+
+    Entity-backed counterpart to :func:`emit_learnings_generated`, currently
+    adopted by two of the non-extraction learning-mutation paths —
+    resumable-extraction finalization and aggregation — the callers with
+    durable per-record ids in scope. Extraction, reflection, and offline-tuner
+    auto-apply do not have a safe 1:1 id per unit of count (see
+    :func:`record_learnings_generated_records`) and use the count-based
+    :func:`emit_learnings_generated` fallback instead. Same guard semantics:
+    config resolution and emission are wrapped and any exception is logged
+    and swallowed — the product path must never fail because metering
+    failed. No-op when ``learning_ids`` is empty.
+
+    Args:
+        org_id: Organisation identifier.
+        configurator: Object exposing ``get_config()`` for platform-LLM resolution.
+        learning_ids: Ids of the learnings durably produced by this path.
+        source: Metering source/path label (e.g. ``"reflection"``).
+        pipeline: Optional pipeline tag (e.g. ``"playbook"``).
+        user_id: Optional user ID tied to the generated learning.
+        request_id: Optional request correlation ID.
+        agent_version: Optional agent version tied to the generated learning.
+        playbook_name: Optional playbook name for playbook learnings.
+        entity_type: Optional entity type (e.g. ``"profile"``).
+        metadata: Optional path-specific usage metadata (shared across events).
+    """
+    if not learning_ids:
+        return
+    try:
+        from reflexio.server.billing_signals import platform_llm_from_config
+
+        config = configurator.get_config()
+        record_learnings_generated_records(
+            org_id=org_id,
+            learning_ids=learning_ids,
+            platform_llm=platform_llm_from_config(config),
+            platform_storage=None,
+            pipeline=pipeline,
+            user_id=user_id,
+            request_id=request_id,
+            source=source,
+            agent_version=agent_version,
+            playbook_name=playbook_name,
+            entity_type=entity_type,
+            metadata=metadata,
+        )
+    except Exception:
+        logger.warning(
+            "emit_learnings_generated_records failed for source=%s org=%s; "
+            "learnings_generated events not emitted",
+            source,
+            org_id,
+            exc_info=True,
+        )
+
+
 def record_applied_learnings(
     *,
     org_id: str,
@@ -114,6 +367,8 @@ def record_applied_learnings(
     """Emit the Application line — surfaced top-K learnings.
 
     No-op unless ``caller_type == "production_agent"`` AND ``surfaced_count > 0``.
+    Each call mints a fresh ``event_key=f"applied:{uuid4()}"`` — a distinct
+    key per search-response moment, never collapsed by ``request_id``.
 
     Args:
         org_id: Organisation identifier.
@@ -134,6 +389,7 @@ def record_applied_learnings(
         pipeline=pipeline,
         request_id=request_id,
         session_id=session_id,
+        event_key=f"applied:{uuid.uuid4()}",
         count_value=surfaced_count,
         platform_llm=platform_llm,
         platform_storage=platform_storage,
@@ -152,7 +408,10 @@ def record_search_request(
 
     No-op unless ``caller_type == "production_agent"``. Unlike
     :func:`record_applied_learnings`, empty search responses still count because
-    this measures requests made, not learnings surfaced.
+    this measures requests made, not learnings surfaced. Each call mints a
+    fresh ``event_key=f"search:{uuid4()}"`` — a distinct key per request, so
+    two searches under the same ``request_id`` are never collapsed into one
+    billed event downstream.
 
     Args:
         org_id: Organisation identifier.
@@ -168,6 +427,7 @@ def record_search_request(
         event_category="application",
         request_id=request_id,
         session_id=session_id,
+        event_key=f"search:{uuid.uuid4()}",
         count_value=1,
         caller_type=caller_type,
     )