ltcai 9.9.3 → 9.9.4

package/lattice_brain/graph/projection.py

@@ -4,6 +4,22 @@ from __future__ import annotations
 
 from ._kg_common import *  # noqa: F403,F401
 
+# ── promotion review mode (review 2026-07-25 Wave 4) ─────────────────────────
+# When enabled, curate() parks would-be Topic promotions in graph_meta for a
+# human decision instead of writing them immediately. Explicit review_mode=
+# argument wins; otherwise this env opt-in decides; default stays auto-promote.
+_PROMOTION_REVIEW_ENV = "LATTICEAI_GRAPH_PROMOTION_REVIEW"
+_PENDING_PROMOTIONS_KEY = "pending_promotions"
+_PENDING_PROMOTIONS_CAP = 100
+
+# graph_meta stamp written by an applied (dry_run=False) noise-curate run; the
+# Command Center hygiene advisory reads it to pace its suggestion (Wave 2.5).
+_LAST_NOISE_CURATE_KEY = "last_noise_curate_at"
+
+
+def _promotion_review_default() -> bool:
+    return os.getenv(_PROMOTION_REVIEW_ENV, "").strip().lower() in ("1", "true", "yes")
+
 
 class KnowledgeGraphProjectionMixin:
     _FTS_SQL = """
@@ -408,7 +424,11 @@ class KnowledgeGraphProjectionMixin:
             )
 
     def curate(
-        self, *, max_documents: int = 200, max_new_nodes: int = 8
+        self,
+        *,
+        max_documents: int = 200,
+        max_new_nodes: int = 8,
+        review_mode: Optional[bool] = None,
     ) -> Dict[str, Any]:
         """On-demand graph curation (T4.4 — graph_curator goes live).
 
@@ -418,6 +438,14 @@ class KnowledgeGraphProjectionMixin:
         Topic nodes (with MENTIONS edges back to their sources and a real
         importance_score in nodes_v2). Explicit and observable — the result
         reports everything promoted AND everything skipped, with reasons.
+
+        ``review_mode`` (review 2026-07-25 Wave 4): when True, nothing is
+        written — the would-be promotions are parked in ``graph_meta`` as
+        ``pending_promotions`` for a human decision via
+        :meth:`apply_pending_promotions` / :meth:`reject_pending_promotions`.
+        Explicit argument wins; ``None`` falls back to the
+        ``LATTICEAI_GRAPH_PROMOTION_REVIEW`` env opt-in; default stays the
+        historical auto-promote behavior.
         """
         from .curator import auto_build_graph_overlay
 
@@ -464,46 +492,37 @@ class KnowledgeGraphProjectionMixin:
             existing_node_labels=existing_labels,
             max_new_nodes=max(1, min(int(max_new_nodes), 50)),
         )
+        valid_ids = {row["id"] for row in rows}
+        review = review_mode if review_mode is not None else _promotion_review_default()
+        if review:
+            proposed_at = _now()
+            proposed = [
+                {
+                    "id": f"topic:{_slug(promo['label'])}",
+                    "label": promo["label"],
+                    "importance": promo["importance"],
+                    "aliases": promo["aliases"],
+                    "sources": [s for s in promo["sources"][:10] if s in valid_ids],
+                    "proposed_at": proposed_at,
+                }
+                for promo in overlay["promotions"]
+            ]
+            with self._connect() as conn:
+                merged = self._merge_pending_promotions(conn, proposed)
+            return {
+                "status": "pending_review",
+                "documents_scanned": len(documents),
+                "candidates_total": overlay["candidates_total"],
+                "pending": proposed,
+                "pending_total": len(merged),
+                "skipped": overlay["skipped"][:50],
+                "skipped_total": len(overlay["skipped"]),
+            }
         promoted: List[Dict[str, Any]] = []
         with self._connect() as conn:
-            valid_ids = {row["id"] for row in rows}
             for promo in overlay["promotions"]:
-                topic_id = f"topic:{_slug(promo['label'])}"
-                self._upsert_node(
-                    conn,
-                    topic_id,
-                    "Topic",
-                    promo["label"],
-                    metadata={
-                        "curated": True,
-                        "importance": promo["importance"],
-                        "aliases": promo["aliases"],
-                        "source": "graph_curator",
-                    },
-                )
-                conn.execute(
-                    "UPDATE nodes_v2 SET importance_score=? WHERE id=?",
-                    (float(promo["importance"]), topic_id),
-                )
-                linked = 0
-                for source_id in promo["sources"][:10]:
-                    if source_id in valid_ids:
-                        self._upsert_edge(
-                            conn,
-                            source_id,
-                            topic_id,
-                            "MENTIONS",
-                            weight=0.6,
-                            metadata={"source": "graph_curator"},
-                        )
-                        linked += 1
                 promoted.append(
-                    {
-                        "node_id": topic_id,
-                        "label": promo["label"],
-                        "importance": promo["importance"],
-                        "linked_sources": linked,
-                    }
+                    self._write_promotion(conn, promo, valid_source_ids=valid_ids)
                 )
         return {
             "status": "ok",
@@ -514,6 +533,148 @@ class KnowledgeGraphProjectionMixin:
             "skipped_total": len(overlay["skipped"]),
         }
 
+    def _write_promotion(
+        self,
+        conn: sqlite3.Connection,
+        promo: Dict[str, Any],
+        *,
+        valid_source_ids: Optional[set] = None,
+    ) -> Dict[str, Any]:
+        """Write one curator promotion: Topic node + importance + MENTIONS edges.
+
+        Single write path shared by direct ``curate()`` and
+        :meth:`apply_pending_promotions`, so a human-approved promotion lands
+        exactly like an auto-promoted one. ``valid_source_ids`` restricts the
+        linkable sources to this curate run's scanned rows; when ``None``
+        (apply-after-review), each stored source is checked for existence so a
+        node deleted between propose and apply is skipped, not an error.
+        """
+        topic_id = str(promo.get("id") or f"topic:{_slug(str(promo['label']))}")
+        self._upsert_node(
+            conn,
+            topic_id,
+            "Topic",
+            str(promo["label"]),
+            metadata={
+                "curated": True,
+                "importance": promo["importance"],
+                "aliases": list(promo.get("aliases") or []),
+                "source": "graph_curator",
+            },
+        )
+        conn.execute(
+            "UPDATE nodes_v2 SET importance_score=? WHERE id=?",
+            (float(promo["importance"]), topic_id),
+        )
+        linked = 0
+        for source_id in list(promo.get("sources") or [])[:10]:
+            if valid_source_ids is not None:
+                if source_id not in valid_source_ids:
+                    continue
+            elif not conn.execute(
+                "SELECT 1 FROM nodes WHERE id=?", (source_id,)
+            ).fetchone():
+                continue
+            self._upsert_edge(
+                conn,
+                source_id,
+                topic_id,
+                "MENTIONS",
+                weight=0.6,
+                metadata={"source": "graph_curator"},
+            )
+            linked += 1
+        return {
+            "node_id": topic_id,
+            "label": promo["label"],
+            "importance": promo["importance"],
+            "linked_sources": linked,
+        }
+
+    # ── pending promotion queue (review 2026-07-25 Wave 4) ───────────────────
+
+    def _read_pending_promotions(
+        self, conn: sqlite3.Connection
+    ) -> List[Dict[str, Any]]:
+        try:
+            row = conn.execute(
+                "SELECT value FROM graph_meta WHERE key=?",
+                (_PENDING_PROMOTIONS_KEY,),
+            ).fetchone()
+        except sqlite3.Error:
+            return []
+        if not row or not row["value"]:
+            return []
+        try:
+            parsed = json.loads(row["value"])
+        except (TypeError, ValueError):
+            return []
+        if not isinstance(parsed, list):
+            return []
+        return [
+            item for item in parsed if isinstance(item, dict) and item.get("id")
+        ]
+
+    def _store_pending_promotions(
+        self, conn: sqlite3.Connection, entries: List[Dict[str, Any]]
+    ) -> None:
+        conn.execute(
+            "INSERT OR REPLACE INTO graph_meta(key, value) VALUES (?, ?)",
+            (_PENDING_PROMOTIONS_KEY, json.dumps(entries, ensure_ascii=False)),
+        )
+
+    def _merge_pending_promotions(
+        self, conn: sqlite3.Connection, proposed: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """Merge new proposals into the stored queue (dedupe by id, cap 100)."""
+        merged: Dict[str, Dict[str, Any]] = {}
+        for item in self._read_pending_promotions(conn) + list(proposed):
+            merged[str(item["id"])] = item  # newest proposal wins per id
+        entries = list(merged.values())[-_PENDING_PROMOTIONS_CAP:]
+        self._store_pending_promotions(conn, entries)
+        return entries
+
+    def pending_promotions(self) -> List[Dict[str, Any]]:
+        """List promotions waiting for a human decision (review mode)."""
+        with self._connect() as conn:
+            return self._read_pending_promotions(conn)
+
+    def apply_pending_promotions(
+        self, ids: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """Apply stored pending promotions (all of them when ``ids`` is None).
+
+        Uses the exact node-writing path as direct ``curate()`` via
+        :meth:`_write_promotion`; applied entries leave the queue.
+        """
+        wanted = None if ids is None else {str(item) for item in ids}
+        applied: List[Dict[str, Any]] = []
+        remaining: List[Dict[str, Any]] = []
+        with self._connect() as conn:
+            for promo in self._read_pending_promotions(conn):
+                if wanted is not None and str(promo.get("id")) not in wanted:
+                    remaining.append(promo)
+                    continue
+                applied.append(self._write_promotion(conn, promo))
+            self._store_pending_promotions(conn, remaining)
+        return {"status": "ok", "applied": applied, "remaining": len(remaining)}
+
+    def reject_pending_promotions(
+        self, ids: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """Drop pending promotions without writing (all when ``ids`` is None)."""
+        wanted = None if ids is None else {str(item) for item in ids}
+        rejected: List[str] = []
+        remaining: List[Dict[str, Any]] = []
+        with self._connect() as conn:
+            for promo in self._read_pending_promotions(conn):
+                if wanted is not None and str(promo.get("id")) not in wanted:
+                    remaining.append(promo)
+                    continue
+                rejected.append(str(promo.get("id")))
+            self._store_pending_promotions(conn, remaining)
+        return {"status": "ok", "rejected": rejected, "remaining": len(remaining)}
+
     _NOISE_CONTENT_TYPES = (
         "Document",
         "File",
@@ -651,6 +812,13 @@ class KnowledgeGraphProjectionMixin:
                         (canonical, original),
                     )
                     conn.execute("DELETE FROM edges WHERE type=?", (original,))
+                # Stamp every applied run — even a no-op one means the graph
+                # was inspected, so the Command Center hygiene advisory
+                # (review 2026-07-25 Wave 2.5) stops re-suggesting for a while.
+                conn.execute(
+                    "INSERT OR REPLACE INTO graph_meta(key, value) VALUES (?, ?)",
+                    (_LAST_NOISE_CURATE_KEY, _now()),
+                )
 
         return {
             "status": "ok",
@@ -675,6 +843,22 @@ class KnowledgeGraphProjectionMixin:
             },
         }
 
+    def last_noise_curate_at(self) -> Optional[str]:
+        """Timestamp of the last applied (dry_run=False) noise-curate run.
+
+        ``None`` when the job never ran or the meta table is unreadable —
+        advisory readers treat both as "curation is due" (fail-open).
+        """
+        try:
+            with self._connect() as conn:
+                row = conn.execute(
+                    "SELECT value FROM graph_meta WHERE key=?",
+                    (_LAST_NOISE_CURATE_KEY,),
+                ).fetchone()
+        except sqlite3.Error:
+            return None
+        return str(row["value"]) if row and row["value"] else None
+
     def mark_superseded(self, old_node_id: str, new_node_id: str) -> Dict[str, Any]:
         """Record that ``old_node_id`` was replaced by ``new_node_id``.
 

package/lattice_brain/graph/retrieval.py

@@ -478,10 +478,16 @@ class KnowledgeGraphRetrievalMixin:
         richer ``allowed_workspaces`` set wins when both are provided.
 
         ``alpha=None`` (the default) resolves the vector share from the
-        query-class fusion table (:mod:`lattice_brain.graph.fusion`):
-        fact 0.6 (the historical default) / code 0.35 / person 0.45 /
-        recency 0.5, config-overridable via ``LATTICEAI_FUSION_WEIGHTS``.
-        Passing an explicit ``alpha`` pins it exactly as before.
+        single retrieval policy (:mod:`lattice_brain.graph.retrieval_policy`,
+        which wraps the query-class fusion table): fact 0.6 (the historical
+        default) / code 0.35 / person 0.45 / recency 0.5, config-overridable
+        via ``LATTICEAI_FUSION_WEIGHTS``. The policy also supplies a
+        deterministic rule-based query rewrite (echoed additively under
+        ``"policy"``; the response ``"query"`` stays the original) and, for
+        the ``recency`` class only, an age-decay half-life that dampens each
+        fused score into the ``[0.5, 1.0]`` band (``scores.age_decay``).
+        Passing an explicit ``alpha`` pins it exactly as before and disables
+        rewrite + decay.
         """
         query = str(query or "").strip()
         try:
@@ -490,14 +496,24 @@ class KnowledgeGraphRetrievalMixin:
             top_k = 20
         top_k = max(1, min(top_k, 100))
         query_class: Optional[str] = None
+        search_query = query
+        rewrite_rules: List[str] = []
+        recency_half_life_days: Optional[float] = None
         if alpha is None:
             try:
-                from .fusion import fusion_profile
+                from .retrieval_policy import resolve_policy
 
-                profile = fusion_profile(query)
-                query_class = profile["query_class"]
-                alpha = float(profile["alpha"])
-            except Exception:  # noqa: BLE001 — fusion table must never break search
+                policy = resolve_policy(query)
+                query_class = policy["query_class"]
+                alpha = float(policy["alpha"])
+                rewrite_rules = list(policy.get("rewrite_rules") or [])
+                rewritten = str(policy.get("search_query") or "")
+                if rewritten and rewritten != query:
+                    search_query = rewritten
+                half_life = policy.get("recency_half_life_days")
+                if half_life is not None:
+                    recency_half_life_days = float(half_life)
+            except Exception:  # noqa: BLE001 — policy resolution must never break search
                 alpha = 0.6
         try:
             alpha = float(alpha)
@@ -516,6 +532,7 @@ class KnowledgeGraphRetrievalMixin:
                 "top_k": top_k,
                 "sources": {"lexical": 0, "vector": 0},
                 "matches": [],
+                "policy": {"search_query": search_query, "rewrite_rules": rewrite_rules},
                 "detail": None,
             }
 
@@ -523,7 +540,7 @@ class KnowledgeGraphRetrievalMixin:
         vec_fetch = max(1, min(int(vector_limit or max(top_k * 2, 20)), 100))
 
         lexical_matches = self.search(
-            query,
+            search_query,
             lex_fetch,
             allowed_workspaces=allowed_workspaces,
             include_legacy_global=include_legacy_global,
@@ -539,7 +556,7 @@ class KnowledgeGraphRetrievalMixin:
         else:
             try:
                 vector_matches = list(
-                    (vector_fn(query, limit=vec_fetch, min_score=min_vector_score) or {}).get(
+                    (vector_fn(search_query, limit=vec_fetch, min_score=min_vector_score) or {}).get(
                         "matches", []
                     )
                 )
@@ -547,6 +564,17 @@ class KnowledgeGraphRetrievalMixin:
                 mode = "lexical_only"
                 detail = f"vector index unavailable: {exc}"
                 vector_matches = []
+        # An embedder swap makes the vector channel silently return zero rows
+        # (vector_search filters on the CURRENT model/dim). Surface the honest
+        # cause additively without changing the mode string.
+        vector_degraded: Optional[str] = None
+        if mode == "hybrid" and not vector_matches:
+            try:
+                fingerprint_fn = getattr(self, "embedder_fingerprint_status", None)
+                if callable(fingerprint_fn) and fingerprint_fn().get("stale_embedder"):
+                    vector_degraded = "stale_embedder"
+            except Exception:  # noqa: BLE001 — fingerprint status must never break search
+                vector_degraded = None
         if vector_matches and allowed_workspaces is not None:
             vector_matches = self.filter_scoped_nodes(
                 vector_matches,
@@ -633,11 +661,28 @@ class KnowledgeGraphRetrievalMixin:
                 entry["fusion"] = "lexical"
             matches.append(entry)
 
+        # Recency-class age decay (retrieval_policy): dampen each fused score
+        # into the [0.5, 1.0] band so old-but-relevant items sink without ever
+        # being zeroed. Other classes skip this block byte-identically.
+        if recency_half_life_days is not None:
+            decay_now = datetime.now()
+            for match in matches:
+                stamp = match.get("updated_at")
+                if _parse_iso(stamp):
+                    multiplier = 0.5 + 0.5 * _recency_score(
+                        stamp, now=decay_now, half_life_days=recency_half_life_days
+                    )
+                else:
+                    # Unknown age is not evidence of staleness — never dampen.
+                    multiplier = 1.0
+                match["scores"]["age_decay"] = round(multiplier, 6)
+                match["score"] = round(float(match["score"]) * multiplier, 6)
+
         matches.sort(key=lambda item: (-item["score"], item["node_id"]))
         matches = matches[:top_k]
         for rank, match in enumerate(matches, start=1):
             match["rank"] = rank
-        return {
+        result = {
             "query": query,
             "mode": mode,
             "alpha": alpha,
@@ -645,8 +690,12 @@ class KnowledgeGraphRetrievalMixin:
             "top_k": top_k,
             "sources": {"lexical": len(lexical_matches), "vector": len(vector_matches)},
             "matches": matches,
+            "policy": {"search_query": search_query, "rewrite_rules": rewrite_rules},
             "detail": detail,
         }
+        if vector_degraded is not None:
+            result["vector_degraded"] = vector_degraded
+        return result
 
     def context_for_query(
         self,

package/lattice_brain/graph/retrieval_policy.py

@@ -0,0 +1,174 @@
+"""Single retrieval policy consulted by both hybrid fusion layers.
+
+Review 2026-07-25 (UX/harness/loop/KG-RAG), Wave 0.2 — "RetrievalPolicy
+단일화" + "query rewrite" + "recency age decay". Before this module the two
+hybrid entry points (``KnowledgeGraphStore.hybrid_search`` two-channel
+alpha fusion and ``SearchService.hybrid_search`` three-channel weight
+fusion) each resolved :func:`lattice_brain.graph.fusion.fusion_profile`
+independently and had no shared place to hang retrieval-wide behavior.
+This module is that single place:
+
+* :func:`rewrite_query` — deterministic, rule-based ko/en normalization
+  (NO LLM). Strips a conservative fixed list of leading/trailing politeness
+  fillers ("~좀 알려줘", "궁금해", "뭐였지", "what is", "please", …) and
+  collapses repeated whitespace. Code-class queries pass through untouched
+  (except whitespace collapse) because exact identifiers/filenames ARE the
+  retrieval signal. ``LATTICEAI_QUERY_REWRITE=0`` disables rewriting.
+* :func:`resolve_policy` — composes the rewrite with
+  :func:`~lattice_brain.graph.fusion.fusion_profile` (the weight table is
+  NOT duplicated here) and adds ``recency_half_life_days``, which is
+  non-``None`` ONLY for the ``recency`` query class — the honest signal
+  that age decay applies exactly where the fusion layers wire it.
+
+Both functions are pure, deterministic, and never raise; the ``fact``
+query class resolves to the historical default weights, so fact-class
+behavior stays byte-compatible. Scores are never combined with ``or``
+(score ``0.0`` is falsy but valid).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Dict, List, Mapping, Optional
+
+from .fusion import classify_query, fusion_profile
+
+QUERY_REWRITE_ENV = "LATTICEAI_QUERY_REWRITE"
+
+# Half-life (days) for the recency-class age decay. Matches the default of
+# lattice_brain.graph._kg_fsutil._recency_score, which the fusion layers use
+# to compute the actual multiplier — this module only declares the policy.
+RECENCY_HALF_LIFE_DAYS = 14.0
+
+# A filler strip is applied only when the remaining query keeps at least this
+# many characters — never rewrite a query down to (near-)nothing.
+_MIN_REMAINDER_CHARS = 4
+
+_WS_RE = re.compile(r"\s+")
+
+# Conservative trailing Korean politeness/filler phrases ("… 좀 알려줘",
+# "… 궁금해", "… 뭐였지"). Anchored at end-of-string, must start the query or
+# follow whitespace so word interiors are never clipped.
+_KO_FILLER_TAIL_RE = re.compile(
+    r"(?:^|(?<=\s))(?:좀\s+)?"
+    r"(?:알려\s*줘요?|알려\s*주세요|알려\s*줄래요?"
+    r"|말해\s*줘요?|말해\s*주세요"
+    r"|설명해\s*줘요?|설명해\s*주세요"
+    r"|궁금해요?|궁금합니다"
+    r"|뭐였지|뭐였더라|뭐더라|뭐지|뭐야"
+    r")\s*[?!.…~]*\s*$"
+)
+
+# Conservative leading English filler ("what is …", "tell me about …",
+# optionally prefixed with "please").
+_EN_FILLER_LEAD_RE = re.compile(
+    r"^(?:please\s+)?(?:tell\s+me\s+about|what\s+is|what\s+was|what\s+are|what's)\s+",
+    re.IGNORECASE,
+)
+
+# Conservative trailing English politeness ("…, please?").
+_EN_FILLER_TAIL_RE = re.compile(r"[,\s]*\bplease\b\s*[?!.]*\s*$", re.IGNORECASE)
+
+_FILLER_RULES = (
+    ("strip_filler_ko", _KO_FILLER_TAIL_RE),
+    ("strip_filler_en_leading", _EN_FILLER_LEAD_RE),
+    ("strip_filler_en_trailing", _EN_FILLER_TAIL_RE),
+)
+
+
+def _rewrite_enabled() -> bool:
+    raw = os.getenv(QUERY_REWRITE_ENV, "").strip().lower()
+    return raw not in {"0", "false", "no", "off"}
+
+
+def rewrite_query(query: Any) -> Dict[str, Any]:
+    """Deterministic rule-based ko/en query normalization (never raises).
+
+    Returns ``{"original": str, "rewritten": str, "rules": [rule names]}``.
+    Only three conservative rules exist: whitespace collapse, trailing
+    Korean filler strip, and leading/trailing English filler strip — each
+    filler strip applies only when the remainder keeps >= 4 characters.
+    Code-class queries (exact identifiers/filenames are the signal) are
+    returned unchanged apart from whitespace collapse. The
+    ``LATTICEAI_QUERY_REWRITE=0`` kill-switch disables rewriting entirely
+    (``rewritten == original``). Empty input yields empty output.
+    """
+    try:
+        text = str(query or "").strip()
+    except Exception:  # noqa: BLE001 — rewrite must never raise
+        return {"original": "", "rewritten": "", "rules": []}
+    if not text:
+        return {"original": "", "rewritten": "", "rules": []}
+    original = text
+    if not _rewrite_enabled():
+        return {"original": original, "rewritten": original, "rules": []}
+
+    rules: List[str] = []
+    rewritten = _WS_RE.sub(" ", text).strip()
+    if rewritten != original:
+        rules.append("collapse_whitespace")
+
+    if classify_query(original) == "code":
+        # Exact identifiers/filenames are the retrieval signal — never touch
+        # them (whitespace collapse is the only permitted normalization).
+        return {"original": original, "rewritten": rewritten, "rules": rules}
+
+    for name, pattern in _FILLER_RULES:
+        candidate = pattern.sub("", rewritten).strip()
+        if candidate != rewritten and len(candidate) >= _MIN_REMAINDER_CHARS:
+            rewritten = candidate
+            rules.append(name)
+    return {"original": original, "rewritten": rewritten, "rules": rules}
+
+
+def resolve_policy(
+    query: Any,
+    *,
+    overrides: Optional[Mapping[str, Mapping[str, float]]] = None,
+) -> Dict[str, Any]:
+    """Resolve the full retrieval policy for ``query`` (never raises).
+
+    Composes :func:`rewrite_query` with
+    :func:`~lattice_brain.graph.fusion.fusion_profile` (classification runs
+    on the ORIGINAL query, so ``query_class`` / ``weights`` / ``alpha`` are
+    byte-identical to calling ``fusion_profile`` directly, as both hybrid
+    layers did before this module). Returns::
+
+        {
+          "query_class": "fact" | "code" | "person" | "recency",
+          "weights": {"keyword", "vector", "graph"},   # service fusion
+          "alpha": float,                              # graph-layer fusion
+          "original_query": str,
+          "search_query": str,       # the rewritten form to search with
+          "rewrite_rules": [str],
+          "recency_half_life_days": float | None,      # 14.0 only for recency
+        }
+
+    ``recency_half_life_days`` is non-``None`` only for the ``recency``
+    class — the honest contract that age decay applies exactly where the
+    fusion layers wire it, and nowhere else.
+    """
+    rewrite = rewrite_query(query)
+    profile = fusion_profile(rewrite["original"], overrides=overrides)
+    query_class = profile["query_class"]
+    search_query = rewrite["rewritten"] if rewrite["rewritten"] else rewrite["original"]
+    return {
+        "query_class": query_class,
+        "weights": dict(profile["weights"]),
+        "alpha": float(profile["alpha"]),
+        "original_query": rewrite["original"],
+        "search_query": search_query,
+        "rewrite_rules": list(rewrite["rules"]),
+        "recency_half_life_days": (
+            RECENCY_HALF_LIFE_DAYS if query_class == "recency" else None
+        ),
+    }
+
+
+__all__ = [
+    "QUERY_REWRITE_ENV",
+    "RECENCY_HALF_LIFE_DAYS",
+    "resolve_policy",
+    "rewrite_query",
+]