claude-smart 0.2.49 → 0.2.50

package/plugin/vendor/reflexio/reflexio/server/services/playbook/components/extractor.py

@@ -11,6 +11,7 @@ from reflexio.server.api_endpoints.request_context import RequestContext
 from reflexio.server.llm.litellm_client import LiteLLMClient
 from reflexio.server.llm.model_defaults import ModelRole, resolve_model_name
 from reflexio.server.llm.token_accounting import RunTokenTotals, sum_trace_tokens
+from reflexio.server.services.deferred_learning_plan import ExtractorBookmarkAdvance
 from reflexio.server.services.extraction.outcome import ExtractionOutcome
 from reflexio.server.services.extraction.resumable_agent import (
     run_resumable_extraction_agent,
@@ -172,25 +173,6 @@ class PlaybookExtractor:
         )
         return session_data_models
 
-    def _update_operation_state(
-        self, request_interaction_data_models: list[RequestInteractionDataModel]
-    ) -> None:
-        """
-        Update operation state after processing interactions.
-
-        Args:
-            request_interaction_data_models: The interactions that were processed
-        """
-        all_interactions = extract_interactions_from_request_interaction_data_models(
-            request_interaction_data_models
-        )
-        mgr = self._create_state_manager()
-        mgr.update_extractor_bookmark(
-            extractor_name=get_extractor_name(self.config),
-            processed_interactions=all_interactions,
-            user_id=self.service_config.user_id,
-        )
-
     # ===============================
     # public methods
     # ===============================
@@ -202,10 +184,12 @@ class PlaybookExtractor:
         This extractor handles its own data collection:
         1. Gets interactions based on its config (window size, source filtering)
         2. Applies time range filter for rerun flows
-        3. Updates operation state after processing
+        3. Defers the stride-bookmark advance onto the outcome (applied in persist)
 
         Returns:
-            list[UserPlaybook]: List of extracted user playbook entries
+            An empty list when there are no interactions to process; otherwise an
+            ExtractionOutcome carrying the extracted playbook entries, the
+            resumable run_id (when set), and the deferred bookmark advance.
         """
         # Collect interactions using extractor's own window_size/stride_size settings
         request_interaction_data_models = self._get_interactions()
@@ -217,17 +201,30 @@ class PlaybookExtractor:
 
         user_playbooks = self.extract_playbook_entries(request_interaction_data_models)
 
-        # Update operation state after successful processing
+        # Defer the stride-bookmark advance onto the outcome instead of
+        # self-advancing here (F1): applied downstream — inside the persist
+        # fence on the durable path, or in ``.run()``'s persist half — so it
+        # stays atomic with the playbook row writes. Only produced when output
+        # was generated (bookmark-iff-rows).
+        bookmark_advance: ExtractorBookmarkAdvance | None = None
         if user_playbooks:
-            self._update_operation_state(request_interaction_data_models)
-
-        if self._last_resumable_run_id:
-            return ExtractionOutcome.completed(
-                user_playbooks,
-                run_id=self._last_resumable_run_id,
-                token_totals=self._last_resumable_token_totals,
+            bookmark_advance = ExtractorBookmarkAdvance(
+                extractor_name=get_extractor_name(self.config),
+                processed_interactions=extract_interactions_from_request_interaction_data_models(
+                    request_interaction_data_models
+                ),
+                user_id=self.service_config.user_id,
             )
-        return user_playbooks
+
+        # Always return an ExtractionOutcome so the bookmark advance rides along
+        # even in the non-resumable case; a resumable run also surfaces its
+        # run_id for _agent_runs finalization.
+        return ExtractionOutcome.completed(
+            user_playbooks,
+            run_id=self._last_resumable_run_id,
+            token_totals=self._last_resumable_token_totals,
+            bookmark_advance=bookmark_advance,
+        )
 
     def extract_playbook_entries(
         self, request_interaction_data_models: list[RequestInteractionDataModel]

package/plugin/vendor/reflexio/reflexio/server/services/playbook/playbook_edit_apply.py

@@ -19,6 +19,7 @@ def apply_playbook_edit(
     new_playbook: UserPlaybook,
     source: str,
     request_id: str,
+    skip_embedding: bool = False,
 ) -> int:
     """Insert a replacement playbook then atomically supersede the incumbent.
 
@@ -43,6 +44,12 @@ def apply_playbook_edit(
             non-empty; use the reflection run id (``ReflectionServiceRequest.request_id``)
             or another operation-scoped id. Raises ``ValueError`` immediately
             (before any storage write) when empty, preventing orphaned successor rows.
+        skip_embedding: Forwarded to ``save_user_playbooks``. Defaults to
+            ``False`` (recompute the embedding at write time — what every online
+            / offline-tuner caller relies on). The durable reflection persist
+            path passes ``True`` because the successor's embedding was already
+            precomputed off the writer transaction, so no embedding runs inside
+            the fence.
 
     Returns:
         The ``user_playbook_id`` of the newly inserted playbook, or ``-1`` if
@@ -56,7 +63,7 @@ def apply_playbook_edit(
             "apply_playbook_edit: request_id must be non-empty (operation-run correlation id)"
         )
     new_playbook.source = source
-    storage.save_user_playbooks([new_playbook])
+    storage.save_user_playbooks([new_playbook], skip_embedding=skip_embedding)
     new_id: int = new_playbook.user_playbook_id
 
     ctx = LineageContext(op_kind="revise", actor=source, request_id=request_id)

package/plugin/vendor/reflexio/reflexio/server/services/playbook/service.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from reflexio.server.api_endpoints.request_context import RequestContext
     from reflexio.server.llm.litellm_client import LiteLLMClient
+    from reflexio.server.services.deferred_learning_plan import GenerationComputePlan
     from reflexio.server.services.storage.storage_base import BaseStorage
 
 from reflexio.models.api_schema.internal_schema import RequestInteractionDataModel
@@ -22,22 +23,19 @@ from reflexio.models.api_schema.service_schemas import (
     UserPlaybook,
 )
 from reflexio.models.config_schema import PlaybookConfig
-from reflexio.server.extensions import get_service
-from reflexio.server.operation_limiter import run_with_operation_limit
 from reflexio.server.services.base_generation_service import (
     BaseGenerationService,
     StatusChangeOperation,
 )
-from reflexio.server.services.playbook.aggregation_prompt_processing import (
-    AGGREGATION_PROMPT_PROCESSOR,
+from reflexio.server.services.deferred_learning_plan import PlaybookWritePlan
+from reflexio.server.services.playbook.aggregation_trigger import (
+    maybe_trigger_user_playbook_aggregation,
 )
-from reflexio.server.services.playbook.components.aggregator import PlaybookAggregator
 from reflexio.server.services.playbook.components.extractor import PlaybookExtractor
 from reflexio.server.services.playbook.playbook_service_constants import (
     PlaybookServiceConstants,
 )
 from reflexio.server.services.playbook.playbook_service_utils import (
-    PlaybookAggregatorRequest,
     PlaybookGenerationRequest,
     format_expert_comparison_pairs,
     has_expert_content,
@@ -154,8 +152,9 @@ class PlaybookGenerationService(
         Returns:
             PlaybookGenerationServiceConfig object
         """
+        generation_request_id = request.request_id
         return PlaybookGenerationServiceConfig(
-            request_id=request.request_id,
+            request_id=generation_request_id,
             agent_version=request.agent_version,
             user_id=request.user_id,
             source=request.source,
@@ -290,12 +289,30 @@ class PlaybookGenerationService(
                 all_playbooks.extend(result)
         self._finalize_extracted_items(all_playbooks)
 
-    def _finalize_extracted_items(self, all_playbooks: list[UserPlaybook]) -> None:
-        """Deduplicate, persist, and aggregate extracted user playbook items."""
+    def _resolve_write_plan(
+        self, results: list[list[UserPlaybook]]
+    ) -> PlaybookWritePlan | None:
+        """Compute-half of playbook finalization — NO learning DB write.
+
+        Flattens + ``dedupe_and_drop_empty``, runs the deduplicator (its 2nd
+        LLM call + reads of existing rows), assigns ``source``/``status``, and
+        **precomputes embeddings** on the survivors. Returns a
+        :class:`PlaybookWritePlan` for the persist half, or ``None`` when there
+        is nothing to write (matching the pre-split ``if all_playbooks:`` gate,
+        which suppressed save/lineage/schedulers alike). Issues no
+        ``save_user_playbooks``/``merge_records``/``supersede_*`` — the write is
+        the persist half's job (compute is write-free).
+        """
         from reflexio.server.services.playbook.playbook_service_utils import (
             dedupe_and_drop_empty,
         )
 
+        generation_request_id = self.service_config.request_id  # type: ignore[reportOptionalMemberAccess]
+
+        all_playbooks: list[UserPlaybook] = []
+        for result in results:
+            if isinstance(result, list):
+                all_playbooks.extend(result)
         all_playbooks = dedupe_and_drop_empty(all_playbooks)
 
         # Deduplicate against existing entries in DB when deduplicator is enabled
@@ -324,7 +341,7 @@ class PlaybookGenerationService(
                 merge_groups,
             ) = consolidator.deduplicate(
                 [all_playbooks],
-                self.service_config.request_id,  # type: ignore[reportOptionalMemberAccess]
+                generation_request_id,
                 self.service_config.agent_version,  # type: ignore[reportOptionalMemberAccess]
                 user_id=self.service_config.user_id,  # type: ignore[reportOptionalMemberAccess]
             )
@@ -342,41 +359,115 @@ class PlaybookGenerationService(
 
         logger.info("All user playbook entries: %s", all_playbooks)
 
+        if not all_playbooks:
+            return None
+
         logger.info(
             "Successfully completed %d %s playbook generation for request id: %s",
             len(all_playbooks),
             self._get_service_name(),
-            self.service_config.request_id,  # type: ignore[reportOptionalMemberAccess]
+            generation_request_id,
         )
 
-        # Save results
-        if all_playbooks:
-            try:
-                self.storage.save_user_playbooks(all_playbooks)  # type: ignore[reportOptionalMemberAccess]
-                self._enqueue_user_playbook_optimization(all_playbooks)
-                self._apply_consolidation_lineage(
-                    all_playbooks, merge_groups, existing_ids_to_delete
-                )
-            except Exception as e:
-                logger.error(
-                    "Failed to save %s results for request id: %s due to %s, exception type: %s",
-                    self._get_service_name(),
-                    self.service_config.request_id,  # type: ignore[reportOptionalMemberAccess]
-                    str(e),
-                    type(e).__name__,
-                )
-                raise
+        # Precompute embeddings on the survivors (compute-side, NO DB write). The
+        # persist half passes skip_embedding=True so no embedding runs in the fence.
+        self.storage.precompute_user_playbook_embeddings(all_playbooks)  # type: ignore[reportOptionalMemberAccess]
+
+        return PlaybookWritePlan(
+            request_id=generation_request_id,
+            output_pending_status=self.output_pending_status,
+            skip_aggregation=self.skip_aggregation,
+            new_playbooks=all_playbooks,
+            superseded_ids=existing_ids_to_delete,
+            merge_groups=merge_groups,
+        )
+
+    def _persist_write_plan(self, plan: PlaybookWritePlan) -> None:
+        """Persist-half of playbook finalization — apply the resolved write-plan.
+
+        Issues only the fence-critical row writes: saves the new playbooks
+        (``skip_embedding=True`` — embeddings were precomputed in compute; the
+        save also assigns survivor ids) then materializes the consolidation
+        lineage, which MUST see those survivor ids and so runs AFTER the save.
+        NO LLM / embedding / dedup. The off-thread optimization/aggregation
+        schedulers are NOT here — they fire post-commit in
+        ``emit_generation_side_effects`` (durable / ``.run()``) or right after
+        persist in ``_finalize_extracted_items`` (resume/manual).
+        """
+        if not plan.new_playbooks:
+            return
+        try:
+            self.storage.save_user_playbooks(  # type: ignore[reportOptionalMemberAccess]
+                plan.new_playbooks, skip_embedding=True
+            )
+            self._apply_consolidation_lineage(
+                plan.new_playbooks,
+                plan.merge_groups,
+                plan.superseded_ids,
+                request_id=plan.request_id,
+            )
+        except Exception as e:
+            logger.error(
+                "Failed to save %s results for request id: %s due to %s, exception type: %s",
+                self._get_service_name(),
+                plan.request_id,
+                str(e),
+                type(e).__name__,
+            )
+            raise
+
+    def _dispatch_playbook_schedulers(self, plan: PlaybookWritePlan) -> None:
+        """Fire the off-thread optimization + aggregation schedulers post-persist.
 
-            # Trigger playbook aggregation
-            if not self.output_pending_status and not self.skip_aggregation:
-                logger.info("Trigger playbook aggregation")
-                self._trigger_playbook_aggregation()
+        Phantom-billing gate: on the durable / ``.run()`` path this is invoked
+        from ``emit_generation_side_effects`` (post-commit), so a fence-lost
+        (superseded) job never enqueues optimization or triggers aggregation. On
+        the synchronous resume/manual path the permanent
+        ``_finalize_extracted_items`` wrapper invokes it right after persist,
+        keeping that path identical to the pre-split monolith. The two callers
+        are mutually exclusive, so the schedulers fire exactly once per run.
+        """
+        self._enqueue_user_playbook_optimization(plan.new_playbooks)
+        if not plan.output_pending_status and not plan.skip_aggregation:
+            logger.info("Trigger playbook aggregation")
+            self._trigger_playbook_aggregation()
+
+    def emit_generation_side_effects(self, plan: GenerationComputePlan) -> None:
+        """Post-commit side-effects — base telemetry/billing + playbook schedulers.
+
+        Extends the base emit (``generation_succeeded`` + ② Learning billing)
+        with the off-thread optimization/aggregation schedulers, which move here
+        so they fire only for a fence-winning durable job (never for a
+        superseded one) — the phantom-billing gate.
+        """
+        super().emit_generation_side_effects(plan)
+        write_plan = plan.write_plan
+        if write_plan is not None:
+            self._dispatch_playbook_schedulers(write_plan)
+
+    def _finalize_extracted_items(self, all_playbooks: list[UserPlaybook]) -> None:
+        """Permanent V3 wrapper: compute→persist→schedulers together (no fence).
+
+        Kept for the synchronous resume/manual callers
+        (``ExtractionResumeWorker`` calls this directly). Routes them through the
+        same ``_resolve_write_plan`` (compute) + ``_persist_write_plan``
+        (persist) split the durable worker uses — with no external
+        ``commit_scope`` — then dispatches the same off-thread schedulers, so the
+        result is identical to the pre-split monolith.
+        """
+        plan = self._resolve_write_plan([all_playbooks])
+        if plan is None:
+            return
+        self._persist_write_plan(plan)
+        self._dispatch_playbook_schedulers(plan)
 
     def _apply_consolidation_lineage(
         self,
         saved_playbooks: list[UserPlaybook],
         merge_groups: list[tuple[int, list[int]]],
         existing_ids_to_delete: list[int],
+        *,
+        request_id: str,
     ) -> None:
         """Materialize consolidation merges as lineage tombstones.
 
@@ -393,9 +484,14 @@ class PlaybookGenerationService(
             saved_playbooks: The just-persisted entries (survivor ids assigned).
             merge_groups: ``(survivor_index, source_existing_ids)`` per merge.
             existing_ids_to_delete: ALL archived ids (merge sources + leftovers).
+            request_id: Generation request id — the lineage key recorded on the
+                merge/supersede events. Passed explicitly (from the write-plan)
+                rather than read off ``self.service_config`` so persist stays
+                decoupled from the mutable service config on the fenced path.
         """
         from reflexio.models.api_schema.domain.entities import LineageContext
 
+        generation_request_id = request_id
         merged_source_ids: set[int] = set()
         for survivor_idx, source_ids in merge_groups:
             survivor_id = saved_playbooks[survivor_idx].user_playbook_id
@@ -409,7 +505,7 @@ class PlaybookGenerationService(
                     actor="consolidator",
                     source_ids=[str(s) for s in source_ids],
                     reason="dedup-merge",
-                    request_id=self.service_config.request_id,  # type: ignore[reportOptionalMemberAccess]
+                    request_id=generation_request_id,
                 ),
             )
 
@@ -423,7 +519,7 @@ class PlaybookGenerationService(
             try:
                 superseded_count = self.storage.supersede_user_playbooks_by_ids(  # type: ignore[reportOptionalMemberAccess]
                     leftover_ids,
-                    self.service_config.request_id,  # type: ignore[reportOptionalMemberAccess]
+                    generation_request_id,
                 )
                 logger.info(
                     "Superseded %d split-source existing entries", superseded_count
@@ -528,42 +624,12 @@ class PlaybookGenerationService(
         Trigger playbook aggregation for playbook types that have aggregator config.
         This is called after raw user playbook entries are saved to check if aggregation should run.
         """
-        playbook_config = self._configured_playbook_config()
-        if not playbook_config or not playbook_config.aggregation_config:
-            return
-
-        logger.info("Triggering aggregation")
-
-        # Create aggregator request. Aggregation is singleton — it operates on the
-        # user's whole playbook set, so no name selector is threaded.
-        aggregator_request = PlaybookAggregatorRequest(
-            agent_version=self.service_config.agent_version,  # type: ignore[reportOptionalMemberAccess]
-        )
-
-        # Initialize and run aggregator (synchronous)
-        aggregation_prompt_processor = get_service(AGGREGATION_PROMPT_PROCESSOR)
-        aggregator_kwargs = {}
-        if aggregation_prompt_processor is not None:
-            aggregator_kwargs["aggregation_prompt_processor"] = (
-                aggregation_prompt_processor
-            )
-        aggregator = PlaybookAggregator(
-            llm_client=self.client,
+        maybe_trigger_user_playbook_aggregation(
             request_context=self.request_context,
+            llm_client=self.client,
             agent_version=self.service_config.agent_version,  # type: ignore[reportOptionalMemberAccess]
-            **aggregator_kwargs,
+            reason="playbook_generation",
         )
-        try:
-            run_with_operation_limit(
-                org_id=self.request_context.org_id,
-                operation="aggregation",
-                fn=lambda: aggregator.run(aggregator_request),
-            )
-        except TimeoutError:
-            logger.info(
-                "Skipping inline aggregation for agent_version=%s: aggregation limiter is saturated",
-                self.service_config.agent_version,  # type: ignore[reportOptionalMemberAccess]
-            )
 
     # ===============================
     # Rerun hook implementations (override base class methods)
@@ -646,8 +712,9 @@ class PlaybookGenerationService(
         """
         # Handle rerun requests (have start_time/end_time datetime objects)
         if isinstance(request, RerunPlaybookGenerationRequest):
+            operation_request_id = f"rerun_playbook_{uuid.uuid4().hex[:8]}"
             return PlaybookGenerationRequest(
-                request_id=f"rerun_playbook_{uuid.uuid4().hex[:8]}",
+                request_id=operation_request_id,
                 agent_version=request.agent_version,
                 user_id=user_id,
                 source=request.source,
@@ -660,8 +727,9 @@ class PlaybookGenerationService(
                 auto_run=False,
             )
         # Handle manual requests (ManualPlaybookGenerationRequest)
+        operation_request_id = f"manual_{uuid.uuid4().hex[:8]}"
         return PlaybookGenerationRequest(
-            request_id=f"manual_{uuid.uuid4().hex[:8]}",
+            request_id=operation_request_id,
             agent_version=request.agent_version,
             user_id=user_id,
             source=request.source,

package/plugin/vendor/reflexio/reflexio/server/services/playbook_optimizer/optimizer.py

@@ -20,6 +20,9 @@ from reflexio.models.api_schema.domain.entities import LineageContext
 from reflexio.models.config_schema import PlaybookOptimizerConfig
 from reflexio.server.api_endpoints.request_context import RequestContext
 from reflexio.server.llm.litellm_client import LiteLLMClient
+from reflexio.server.services.playbook.aggregation_trigger import (
+    maybe_trigger_user_playbook_aggregation,
+)
 from reflexio.server.tracing import sentry_tags
 
 from .assistant_webhook import AssistantCallable, LocalScriptAssistant, WebhookAssistant
@@ -488,13 +491,29 @@ class PlaybookOptimizer:
         # the rule wording, so writing ``best_content`` is sufficient — there
         # is no derived polarity label or separate polarity field to keep in
         # sync.
-        return _supersede_user_playbook(
+        successor_id = _supersede_user_playbook(
             self.storage,
             current_user,
             best_content,
             "playbook_optimizer",
             request_id=run_request_id,
         )
+        if successor_id is not None:
+            try:
+                successor = self.storage.get_user_playbook_by_id(successor_id)
+                if successor is not None and successor.agent_version:
+                    maybe_trigger_user_playbook_aggregation(
+                        request_context=self.request_context,
+                        llm_client=self.llm_client,
+                        agent_version=successor.agent_version,
+                        reason="playbook_optimizer",
+                    )
+            except Exception:  # noqa: BLE001
+                logger.exception(
+                    "playbook_optimizer aggregation trigger failed after successor commit",
+                    extra={"successor_id": successor_id},
+                )
+        return successor_id
 
 
 def _agent_like_playbook(playbook: UserPlaybook) -> AgentPlaybook:

package/plugin/vendor/reflexio/reflexio/server/services/playbook_optimizer/scheduler.py

@@ -5,6 +5,9 @@ import logging
 import threading
 import time
 from collections.abc import Callable
+from functools import partial
+
+from reflexio.server.callback_executor import submit_callback
 
 from .optimizer import PlaybookOptimizationRunStatus, PlaybookOptimizationTarget
 
@@ -110,12 +113,16 @@ class PlaybookOptimizationScheduler:
                             continue
                         _, callback, abort_threshold, cooldown_seconds = current
                         del self._scheduled[key]
-                        threading.Thread(
-                            target=self._run_callback,
-                            args=(key, callback, abort_threshold, cooldown_seconds),
-                            daemon=True,
-                            name=f"playbook-opt-{key[1]}-{key[2]}",
-                        ).start()
+                        submit_callback(
+                            f"playbook-opt-{key[1]}-{key[2]}",
+                            partial(
+                                self._run_callback,
+                                key,
+                                callback,
+                                abort_threshold,
+                                cooldown_seconds,
+                            ),
+                        )
             except Exception:
                 logger.exception("Playbook optimization scheduler loop failed")
                 time.sleep(1)

package/plugin/vendor/reflexio/reflexio/server/services/pre_retrieval/_query_reformulator.py

@@ -1,16 +1,19 @@
 """Independent query reformulation module for pre-retrieval optimization.
 
-Reformulates search queries into clean, normalized natural language:
-resolves conversation context, expands abbreviations, fixes grammar.
+Reformulates search queries into clean, normalized natural language AND
+extracts the query's temporal signals (relative time window,
+recency_dominant, wants_current) in the same structured LLM call — so
+retrieval can be time-sensitive with no additional pre-search latency.
 No FTS expansion -- that is handled by document-side expansion at storage time.
 
 Provides two interfaces:
-  - rewrite(): pure query transformation (no search)
+  - rewrite(): pure query transformation + temporal signals (no search)
   - search(): rewrite + execute search via callable + merge results
 """
 
 import logging
 from collections.abc import Callable
+from datetime import UTC, datetime
 from typing import Generic, TypeVar
 
 from pydantic import BaseModel
@@ -84,13 +87,15 @@ class QueryReformulator:
         query: str,
         conversation_history: list[ConversationTurn] | None = None,
     ) -> ReformulationResult:
-        """Reformulate a search query into clean, normalized natural language.
+        """Reformulate a query and extract its temporal signals.
 
-        Always runs reformulation: resolves conversation context (pronouns,
+        One structured LLM call resolves conversation context (pronouns,
         ellipsis, implicit references), expands abbreviations, fixes grammar,
-        and normalizes terminology.
+        normalizes terminology — and reads the question's time semantics
+        (relative window, recency_dominant, wants_current).
 
-        Falls back to the original query on any LLM failure.
+        Falls back to the original query with no temporal signals on any
+        LLM/parse failure.
 
         Args:
             query (str): The original user search query
@@ -98,11 +103,11 @@ class QueryReformulator:
                 context-aware reformulation.
 
         Returns:
-            ReformulationResult: The reformulated standalone query
+            ReformulationResult: Reformulated standalone query + temporal
+                signals.
         """
         try:
-            reformulated = self._reformulate(query, conversation_history)
-            return ReformulationResult(standalone_query=reformulated)
+            return self._reformulate(query, conversation_history)
         except Exception as e:
             logger.warning("Query reformulation failed, using original: %s", e)
             return ReformulationResult(standalone_query=query)
@@ -150,18 +155,21 @@ class QueryReformulator:
         self,
         query: str,
         conversation_history: list[ConversationTurn] | None = None,
-    ) -> str:
-        """Use LLM to reformulate the query into clean, standalone natural language.
+    ) -> ReformulationResult:
+        """One structured LLM call: rewritten query + temporal signals.
 
         Args:
             query (str): The original search query
             conversation_history (list, optional): Prior conversation turns
 
         Returns:
-            str: Reformulated query text
+            ReformulationResult: Validated result. A suspect rewritten-query
+                field degrades the whole result to the original query with no
+                signals (a model that mangles the rewrite is not trusted for
+                the signals either).
 
         Raises:
-            Exception: If LLM call or extraction fails
+            Exception: If the LLM call fails
         """
         conversation_context = self._format_conversation_context(conversation_history)
         conversation_context_block = (
@@ -171,29 +179,36 @@ class QueryReformulator:
         )
         prompt = self.prompt_manager.render_prompt(
             "query_reformulation",
-            {"query": query, "conversation_context_block": conversation_context_block},
+            {
+                "query": query,
+                "conversation_context_block": conversation_context_block,
+                "today_iso": datetime.now(UTC).date().isoformat(),
+            },
         )
         logger.debug("Query reformulation prompt: %s", prompt)
         model_kwargs = {}
         if self.model_name:
             model_kwargs["model"] = self.model_name
-        result = self.llm_client.generate_response(
-            prompt,
+        result = self.llm_client.generate_chat_response(
+            messages=[{"role": "user", "content": prompt}],
+            response_format=ReformulationResult,
             timeout=self.LLM_TIMEOUT,
             max_retries=self.LLM_MAX_RETRIES,
             **model_kwargs,
         )
         log_model_response(logger, "Query reformulation model response", result)
 
-        if isinstance(result, str):
-            extracted = self._extract_reformulated_query(result)
-            if extracted:
-                return extracted
-            logger.warning("LLM returned invalid reformulation: %s", result)
-            return query
+        if not isinstance(result, ReformulationResult):
+            logger.warning("LLM returned non-structured reformulation: %r", result)
+            return ReformulationResult(standalone_query=query)
 
-        logger.warning("LLM returned empty response for query reformulation")
-        return query
+        extracted = self._extract_reformulated_query(result.standalone_query)
+        if not extracted:
+            logger.warning(
+                "LLM returned invalid reformulation: %s", result.standalone_query
+            )
+            return ReformulationResult(standalone_query=query)
+        return result.model_copy(update={"standalone_query": extracted})
 
     @classmethod
     def _extract_reformulated_query(cls, output: str) -> str | None: