nexo-brain 7.32.0 → 7.34.0

package/src/pre_answer_router.py

@@ -565,6 +565,8 @@ _SOURCE_PLANS: dict[str, SourcePlan] = {
             SourceStep("workflows", timeout_ms=260),
             SourceStep("change_log", timeout_ms=260),
             SourceStep("causal_graph", timeout_ms=120, max_chars=900),
+            SourceStep("kg_neighbors", timeout_ms=120, max_chars=900),
+            SourceStep("associative_graph", timeout_ms=120, max_chars=900),
             SourceStep("diary", timeout_ms=260),
         ),
         fallback=(
@@ -592,6 +594,8 @@ _SOURCE_PLANS: dict[str, SourcePlan] = {
             SourceStep("guard_context", timeout_ms=160),
             SourceStep("change_log", timeout_ms=300),
             SourceStep("workflows", timeout_ms=260),
+            SourceStep("kg_neighbors", timeout_ms=120, max_chars=900),
+            SourceStep("associative_graph", timeout_ms=120, max_chars=900),
         ),
         fallback=(
             SourceStep("transcripts", phase="fallback", timeout_ms=650),
@@ -625,6 +629,7 @@ _SOURCE_PLANS: dict[str, SourcePlan] = {
             SourceStep("diary", timeout_ms=280),
             SourceStep("change_log", timeout_ms=300),
             SourceStep("transcripts", timeout_ms=700),
+            SourceStep("kg_neighbors", timeout_ms=120, max_chars=900),
         ),
         fallback=(SourceStep("continuity", phase="fallback", timeout_ms=400),),
     ),
@@ -654,6 +659,7 @@ _SOURCE_PLANS: dict[str, SourcePlan] = {
             SourceStep("project_atlas", timeout_ms=160),
             SourceStep("system_catalog", timeout_ms=420),
             SourceStep("diary", timeout_ms=280),
+            SourceStep("kg_neighbors", timeout_ms=120, max_chars=900),
         ),
         fallback=(
             SourceStep("transcripts", phase="fallback", timeout_ms=700),
@@ -667,6 +673,7 @@ _SOURCE_PLANS: dict[str, SourcePlan] = {
             SourceStep("system_catalog", timeout_ms=420),
             SourceStep("project_atlas", timeout_ms=160),
             SourceStep("runtime_docs", timeout_ms=300),
+            SourceStep("kg_neighbors", timeout_ms=120, max_chars=900),
         ),
         fallback=(
             SourceStep("source_grep", phase="fallback", timeout_ms=600),
@@ -1218,6 +1225,8 @@ def default_source_adapters() -> dict[str, SourceAdapter]:
         "workflows": _source_workflows,
         "change_log": _source_change_log,
         "causal_graph": _source_causal_graph,
+        "kg_neighbors": _source_kg_neighbors,
+        "associative_graph": _source_associative_graph,
         "diary": _source_diary,
         "transcripts": _source_transcripts,
         "memory": _source_memory,
@@ -1710,6 +1719,244 @@ def _source_causal_graph(request: SourceRequest) -> SourceResult:
     )
 
 
+def _source_kg_neighbors(request: SourceRequest) -> SourceResult:
+    """KG neighbors + verified causal/ops edges for entities/files in the query.
+
+    task_close (7.32.0) writes causal/provenance edges but nothing READ the KG at
+    answer time, so the richer non-causal structure (touched/applies_to/belongs_to/
+    mentions/...) never reached an answer. This bounded, fail-open, 1-hop source
+    reads it. Hard-limited (<=3 refs, <=6 neighbors), index-backed, respects the
+    per-source timeout — it can never block the answer.
+    """
+    try:
+        import knowledge_graph as kg
+        import causal_graph
+    except Exception as exc:
+        return SourceResult(source="kg_neighbors", ok=False, skipped=True, aborted_reason="source_error", error=str(exc))
+
+    refs: list[str] = []
+    for raw in (request.files or "").split(","):
+        clean = raw.strip()
+        if clean:
+            refs.append(clean)
+    if not refs:
+        for match in _PATHISH_RE.findall(request.query or ""):
+            refs.append(match)
+        for match in re.findall(r"\b[\w.-]+(?:/[\w.@+-]+)+\b", request.query or ""):
+            refs.append(match)
+    refs = list(dict.fromkeys(refs))
+    if not refs:
+        return SourceResult(source="kg_neighbors")
+
+    rendered_parts: list[str] = []
+    evidence_refs: list[str] = []
+    result_count = 0
+    for ref in refs[:3]:
+        try:
+            node = None
+            for ntype, nref in (("file", ref), ("file", f"file:{ref}"), ("entity", ref), ("entity", f"entity:{ref}")):
+                node = kg.get_node(ntype, nref)
+                if node:
+                    break
+            if node:
+                for nb in kg.get_neighbors(int(node["id"]), active_only=True)[:6]:
+                    relation = str(nb.get("relation") or "")
+                    if relation.startswith("causal:") or relation.startswith("ops:"):
+                        continue  # surfaced via query_edges below (avoid duplicate)
+                    line = f"- {relation} ({nb.get('direction')}) {nb.get('node_type')}:{nb.get('node_ref')}"
+                    if nb.get("label"):
+                        line += f" ({nb.get('label')})"
+                    rendered_parts.append(line)
+                    evidence_refs.append(f"kg:node:{node['id']}:{nb.get('id')}")
+                    result_count += 1
+            cg = causal_graph.query_edges(
+                ref_type="file", ref=ref, project_key=request.area, include_historical=False, limit=4,
+            )
+            if cg.get("has_evidence"):
+                rendered_parts.append(causal_graph.render_query_result(cg, max_chars=request.max_chars))
+                result_count += len(cg.get("edges") or [])
+                for edge in cg.get("edges") or []:
+                    props = edge.get("properties_dict") or {}
+                    evidence_refs.extend(str(i) for i in props.get("evidence_refs") or [] if str(i).strip())
+        except Exception:
+            continue
+    if not rendered_parts:
+        return SourceResult(source="kg_neighbors")
+    return SourceResult(
+        source="kg_neighbors",
+        rendered=_clip("\n".join(rendered_parts), request.max_chars),
+        evidence_refs=list(dict.fromkeys(evidence_refs)),
+        result_count=result_count,
+    )
+
+
+def _associative_graph_basename_match(kg, ref: str, *, limit: int = 3) -> list[int]:
+    """Resolve a bare basename to KG file node ids via one bounded indexed LIKE.
+
+    Only fires for path-ish refs (contains a '.' extension or '/'), so a generic
+    word never triggers a table-wide LIKE. Returns at most ``limit`` node ids.
+    """
+    clean = str(ref or "").strip()
+    if not clean or ("." not in clean and "/" not in clean):
+        return []
+    base = clean.rsplit("/", 1)[-1]
+    if len(base) < 4:
+        return []
+    try:
+        rows = kg._get_db().execute(
+            "SELECT id FROM kg_nodes WHERE node_type='file' AND node_ref LIKE ? LIMIT ?",
+            (f"%{base}", int(limit)),
+        ).fetchall()
+        return [int(r["id"]) for r in rows]
+    except Exception:
+        return []
+
+
+def _associative_graph_seeds(request: SourceRequest, kg, *, max_seeds: int = 8) -> dict[int, float]:
+    """Resolve the personalization vector for the associative-graph PPR.
+
+    Two sources, union'd and capped (plan section 2.1):
+      (i)  entities — entity_live_profile.resolve_entity(limit=8) — only when the
+           query looks entity/path-worthy (reuses the local_context gate so we do
+           NOT scan the entities table on generic queries).
+      (ii) paths/files — request.files or the _PATHISH_RE / slash-token regex,
+           same extraction as kg_neighbors.
+
+    Returns {kg_node_id: weight}. Weight = entity score (i) or 1.0 (ii).
+    """
+    seeds: dict[int, float] = {}
+
+    # (i) Entities — gated by the same worthiness check used for local_context so
+    # generic queries never pay the full-table scan in resolve_entity.
+    if _local_context_query_worthwhile(request):
+        try:
+            import entity_live_profile
+
+            resolved = entity_live_profile.resolve_entity(request.query or "", limit=max_seeds)
+            for cand in (resolved.get("candidates") or [])[:max_seeds]:
+                ent_id = cand.get("entity_id")
+                if not ent_id:
+                    continue
+                node = kg.get_node("entity", f"entity:{ent_id}") or kg.get_node("entity", str(ent_id))
+                if node:
+                    nid = int(node["id"])
+                    score = float(cand.get("score") or 0.0) or 1.0
+                    seeds[nid] = max(seeds.get(nid, 0.0), score)
+        except Exception:
+            pass
+
+    # (ii) Paths / files — identical extraction to kg_neighbors.
+    refs: list[str] = []
+    for raw in (request.files or "").split(","):
+        clean = raw.strip()
+        if clean:
+            refs.append(clean)
+    if not refs:
+        for match in _PATHISH_RE.findall(request.query or ""):
+            refs.append(match)
+        for match in re.findall(r"\b[\w.-]+(?:/[\w.@+-]+)+\b", request.query or ""):
+            refs.append(match)
+    for ref in list(dict.fromkeys(refs)):
+        try:
+            node = None
+            for ntype, nref in (("file", ref), ("file", f"file:{ref}"), ("entity", ref), ("entity", f"entity:{ref}")):
+                node = kg.get_node(ntype, nref)
+                if node:
+                    break
+            if node:
+                seeds.setdefault(int(node["id"]), 1.0)
+            else:
+                # Basename suffix-match: the KG stores files under full paths
+                # (file:/Users/.../foo.py) while a query usually carries the bare
+                # basename (foo.py). One bounded indexed LIKE recovers those — a
+                # capability kg_neighbors (exact-match only) lacks.
+                for nid in _associative_graph_basename_match(kg, ref, limit=3):
+                    seeds.setdefault(nid, 1.0)
+                    if len(seeds) >= max_seeds:
+                        break
+        except Exception:
+            continue
+        if len(seeds) >= max_seeds:
+            break
+
+    # Cap to <=max_seeds (entities first by insertion order, then paths).
+    if len(seeds) > max_seeds:
+        seeds = dict(list(seeds.items())[:max_seeds])
+    return seeds
+
+
+def _source_associative_graph(request: SourceRequest) -> SourceResult:
+    """Multi-hop associative recall via Personalized PageRank over the KG (Ola 2).
+
+    Generalises ``kg_neighbors`` (bounded 1-hop fan-out) to a ranked multi-hop
+    spreading-activation (HippoRAG2-style "connect the dots at answer time").
+    Seeds from query entities + paths, runs a pure-Python forward-push PPR over
+    the active ``kg_edges`` (column-stochastic -> hub-safe), and surfaces the
+    top-ranked related nodes that a 1-hop fan-out would miss.
+
+    Fail-open absolute: any error / missing module / 0 seeds returns a bare
+    SourceResult (no evidence). Bounded by ``max_push`` and the per-source
+    timeout — it can never block the answer. Refs are ``kg:node:<id>`` (cacheable
+    via the resolution_cache global watermark, identical to kg_neighbors).
+    """
+    try:
+        import knowledge_graph as kg
+        import ppr
+    except Exception as exc:
+        return SourceResult(
+            source="associative_graph", ok=False, skipped=True,
+            aborted_reason="source_error", error=str(exc),
+        )
+
+    try:
+        seeds = _associative_graph_seeds(request, kg, max_seeds=ppr.DEFAULT_MAX_SEEDS)
+        if not seeds:
+            return SourceResult(source="associative_graph")
+
+        # Cold-start contract: the FULL graph build (~13k edges) plus a cold
+        # process's imports/first-DB-touch overruns the 120ms step timeout, which
+        # would make the dispatcher abort the step and the feature contribute
+        # nothing on query-1. So we never build inline. If the per-process cache
+        # is already warm (query-2+, or a process whose pre-warm finished), we run
+        # the multi-hop PPR straight off the cached graph (~5-7ms). If it is cold,
+        # we kick off a non-blocking background pre-warm and degrade THIS query to
+        # the bounded 1-hop fan-out (parity with kg_neighbors) — fast, never times
+        # out — so the next query gets multi-hop.
+        if ppr.cache_is_warm():
+            ranked = ppr.rank_related(seeds, top_n=ppr.DEFAULT_TOP_N)
+            if not ranked:
+                # Warm but PPR returned nothing (e.g. seeds isolated) -> 1-hop.
+                ranked = ppr.fallback_neighbors(list(seeds), limit=6)
+        else:
+            ppr.prewarm_async()
+            ranked = ppr.fallback_neighbors(list(seeds), limit=6)
+        if not ranked:
+            return SourceResult(source="associative_graph")
+
+        rendered_parts: list[str] = []
+        evidence_refs: list[str] = []
+        for node in ranked:
+            line = f"- {node.node_type}:{node.node_ref}"
+            if node.label:
+                line += f" ({node.label})"
+            if node.score:
+                line += f" [ppr={node.score:.4f}]"
+            rendered_parts.append(line)
+            evidence_refs.append(f"kg:node:{node.node_id}")
+
+        return SourceResult(
+            source="associative_graph",
+            rendered=_clip("\n".join(rendered_parts), request.max_chars),
+            evidence_refs=list(dict.fromkeys(evidence_refs)),
+            result_count=len(ranked),
+        )
+    except Exception as exc:
+        return SourceResult(
+            source="associative_graph", ok=False, skipped=True,
+            aborted_reason="source_error", error=str(exc),
+        )
+
+
 def _source_diary(request: SourceRequest) -> SourceResult:
     from db import read_session_diary
 
@@ -1784,7 +2031,28 @@ def _source_memory(request: SourceRequest) -> SourceResult:
     from db import recall
 
     rows = recall(request.query, days=45)[:5]
-    return _rows_result("memory", rows, ("source", "title", "snippet", "category"), request.max_chars)
+    # ``recall`` returns heterogeneous FTS rows keyed by (source, source_id) in
+    # the unified_search index, NOT a single ``id`` column. The default
+    # ``_rows_result`` ref would collapse to a POSITIONAL ``memory:<idx>`` that
+    # identifies no row, so the resolution cache could not version it (and would
+    # refuse to cache, or worse, serve stale). Emit a RESOLVABLE ref
+    # ``memory:<source>:<source_id>`` that the cache versions via
+    # unified_search(source, source_id).updated_at, so an edited memory row
+    # invalidates the cached answer. Falls back to the positional ref only when
+    # a row carries no (source, source_id) pair (which the cache then treats as
+    # untrackable and refuses to cache — conservative, never stale).
+    if not rows:
+        return SourceResult(source="memory")
+    result = _rows_result("memory", rows, ("source", "title", "snippet", "category"), request.max_chars)
+    resolvable_refs: list[str] = []
+    for row in rows[:5]:
+        src = str(row.get("source") or "").strip()
+        sid = str(row.get("source_id") or "").strip()
+        if src and sid:
+            resolvable_refs.append(f"memory:{src}:{sid}")
+    if resolvable_refs:
+        result.evidence_refs = resolvable_refs
+    return result
 
 
 def _source_project_atlas(request: SourceRequest) -> SourceResult:
@@ -2261,9 +2529,46 @@ def _filter_rows_by_query(rows: Iterable[dict[str, Any]], query: str, fields: tu
     return matched
 
 
-def _rows_result(source: str, rows: list[dict[str, Any]], fields: tuple[str, ...], max_chars: int) -> SourceResult:
+# The resolution-cache versioner (``resolution_cache._SOURCE_VERSIONERS``) looks
+# up each cached ref by an EXACT id-column. If ``_rows_result`` builds the ref
+# from a DIFFERENT column than the versioner reads, ``ref_version`` resolves to
+# the wrong row (or, on a value collision between a free-text id column of one
+# row and the numeric id of another, to a REAL but WRONG row) → editing the row
+# the ref encodes does not move the snapshot → STALE HIT. The generic
+# ``id -> evidence_id -> task_id -> run_id -> session_id -> idx`` chain is exactly
+# such a mismatch source: e.g. a ``session_diary`` row carries BOTH ``id`` (the
+# versioner column) and ``session_id`` (a free-text column the OLD chain never
+# reached because ``id`` won), so the emitted ref and the versioner agreed only
+# by luck — and ``lifecycle_events`` has no ``id`` column at all, so the chain
+# fell through to ``session_id``/positional ``idx`` while the versioner read
+# ``event_id``.
+#
+# ``_ROUTER_REF_ID_FIELD`` pins, per source, the SINGLE column whose value builds
+# the ref. It MUST equal the ``id_column`` the resolution-cache versioner uses
+# for that source so ``ref_version('{source}:{id}')`` resolves to the exact row
+# the ref encodes. When the pinned column is absent/empty on a row, we emit a
+# deliberately positional ``{source}:__row<idx>`` ref: positional refs do not
+# match any id-column, so the write gate refuses to cache them (untrackable) —
+# never a silent fallback to a colliding column. Sources NOT listed here keep the
+# legacy chain (their adapters emit a composite/canonical ref, e.g.
+# ``evidence_ledger`` → ``evidence_id``, or are watermark/untrackable anyway).
+_ROUTER_REF_ID_FIELD: dict[str, str] = {
+    "diary": "id",            # versioner: session_diary.id  (NOT session_id — collides)
+    "runtime_db": "event_id", # versioner: lifecycle_events.event_id (no ``id`` column)
+}
+
+
+def _rows_result(
+    source: str,
+    rows: list[dict[str, Any]],
+    fields: tuple[str, ...],
+    max_chars: int,
+    *,
+    id_field: str | None = None,
+) -> SourceResult:
     if not rows:
         return SourceResult(source=source)
+    pinned = id_field or _ROUTER_REF_ID_FIELD.get(source)
     lines: list[str] = []
     refs: list[str] = []
     for idx, row in enumerate(rows[:5], start=1):
@@ -2273,7 +2578,15 @@ def _rows_result(source: str, rows: list[dict[str, Any]], fields: tuple[str, ...
             if value not in (None, ""):
                 parts.append(f"{field_name}={_clip(str(value), 180)}")
         lines.append(f"- " + " | ".join(parts))
-        ref_id = row.get("id") or row.get("evidence_id") or row.get("task_id") or row.get("run_id") or row.get("session_id") or idx
+        if pinned is not None:
+            # Pinned source: the ref MUST use the same column the versioner reads.
+            value = row.get(pinned)
+            # A positional fallback ref deliberately matches no id-column so the
+            # resolution-cache write gate refuses to cache it (untrackable) rather
+            # than silently emit a ref under a colliding column.
+            ref_id = value if value not in (None, "") else f"__row{idx}"
+        else:
+            ref_id = row.get("id") or row.get("evidence_id") or row.get("task_id") or row.get("run_id") or row.get("session_id") or idx
         refs.append(f"{source}:{ref_id}")
     return SourceResult(
         source=source,

package/src/pre_answer_runtime.py

@@ -12,6 +12,41 @@ from pre_answer_router import DEFAULT_BUDGET_MS, DEFAULT_TOKEN_BUDGET, classify_
 
 RUNTIME_BUDGET_POLICY_VERSION = "runtime_budget_v1"
 
+# Working-memory TTL for "I just resolved this" intents (Francisco's brief:
+# don't re-search project X / "what do you know about María" from zero).
+# Protected by the 3 invalidations (TTL + per-row snapshot + change_watermark),
+# so a real change still forces a fresh resolution regardless of TTL.
+#
+# DEFENSE IN DEPTH: the TTL is now 15 MINUTES (900s), down from 6h. The per-row
+# snapshot is the primary anti-stale guard, but it can only catch a change it can
+# RESOLVE; a short TTL bounds the maximum obsolescence to minutes for anything
+# that ever slips past resolution (a newly-introduced untracked store, a row-
+# correctness regression), without losing the "lo acabo de mirar" repeat-question
+# win — 15 minutes still covers the same-conversation re-ask. Configurable via
+# NEXO_RESOLUTION_CACHE_PRIOR_WORK_TTL (seconds); set to 0 to disable the override
+# and fall back to the tier's short TTL. Instant stays 0 (volatile) and critical
+# keeps its short tier TTL (excluded below).
+WORKING_MEMORY_INTENTS = {
+    "prior_work",
+    "identity_authorship",
+    "live_state_claim",
+    "memory_question",
+}
+_DEFAULT_WORKING_MEMORY_TTL = 15 * 60  # 900s — defense-in-depth obsolescence cap
+
+
+def _working_memory_ttl_override() -> int:
+    import os
+
+    raw = os.environ.get("NEXO_RESOLUTION_CACHE_PRIOR_WORK_TTL")
+    if raw is None or str(raw).strip() == "":
+        return _DEFAULT_WORKING_MEMORY_TTL
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        return _DEFAULT_WORKING_MEMORY_TTL
+    return max(0, value)
+
 HEAVY_SOURCES = {"memory", "cognitive", "local_context", "transcripts"}
 CANONICAL_ROUTER_SOURCES = {
     "semantic_layers",
@@ -22,6 +57,8 @@ CANONICAL_ROUTER_SOURCES = {
     "workflows",
     "change_log",
     "causal_graph",
+    "kg_neighbors",
+    "associative_graph",
     "diary",
     "transcripts",
     "memory",
@@ -89,6 +126,14 @@ def _as_optional_positive_int(value: Any) -> int | None:
     return number if number > 0 else None
 
 
+def _truthy(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return False
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
 def _clean(value: Any) -> str:
     return " ".join(str(value or "").strip().lower().split())
 
@@ -327,6 +372,22 @@ def select_budget_policy(
             required_checks.append("server_verification")
         if clean_area in {"billing", "legal", "external_publication"}:
             required_checks.append("permissions")
+    cache_ttl_seconds = int(spec.get("cache_ttl_seconds") or 0)
+    # Working-memory TTL: extend caching for "I just resolved this" intents so a
+    # repeat question in the same window is served from memory instead of a cold
+    # re-search. Never applied to instant (ttl=0, volatile) or critical
+    # (release/server/billing/legal must keep their short ttl). Safe because the
+    # source_fingerprint + change_watermark invalidations still fire.
+    if (
+        cache_ttl_seconds > 0
+        and tier != "critical"
+        and intent in WORKING_MEMORY_INTENTS
+    ):
+        override = _working_memory_ttl_override()
+        if override > cache_ttl_seconds:
+            cache_ttl_seconds = override
+            reasons.append("working_memory_ttl_extended")
+
     deadline_ms = int(spec["deadline_ms"])
     token_budget = int(spec["token_budget"])
     if budget_ms_override is not None:
@@ -381,7 +442,7 @@ def select_budget_policy(
         can_delay_first_response=bool(spec.get("can_delay_first_response", False)),
         must_disclose_gap=bool(spec.get("must_disclose_gap", False)),
         delay_message_threshold_ms=int(spec.get("delay_message_threshold_ms") or 0),
-        cache_ttl_seconds=int(spec.get("cache_ttl_seconds") or 0),
+        cache_ttl_seconds=cache_ttl_seconds,
         route_cache_key=route_key,
         privacy_level=str(spec.get("privacy_level") or "normal"),
         reason_codes=tuple(dict.fromkeys(reasons)),
@@ -485,6 +546,69 @@ def run_pre_answer_route(
         budget_ms_override=_as_optional_positive_int(payload.get("budget_ms")),
         token_budget_override=_as_optional_positive_int(payload.get("token_budget")),
     )
+
+    # ── FAST-PATH: working-memory / resolution cache ──────────────────────
+    # The cache key (route_cache_key) and TTL (cache_ttl_seconds) were already
+    # computed by select_budget_policy; here we finally READ them. A valid hit
+    # serves the prior FINAL result without re-running route_pre_answer or the
+    # escalation pass. 'instant' tier (ttl=0) never caches. The anti-stale
+    # contract (TTL + status + source_fingerprint + change_watermark) lives in
+    # resolution_cache.is_valid — any failure is a MISS and falls through.
+    sid = str(payload.get("sid") or payload.get("session_id") or "")
+    cache_enabled = (
+        policy.cache_ttl_seconds > 0
+        and bool(policy.route_cache_key)
+        and not _truthy(payload.get("no_cache"))
+        and not _truthy(payload.get("bypass_cache"))
+    )
+    if cache_enabled:
+        try:
+            import resolution_cache
+
+            expected_sid = sid if policy.intent in resolution_cache.SESSION_SCOPED_INTENTS else ""
+            hit = resolution_cache.get(policy.route_cache_key, expected_sid=expected_sid)
+        except Exception:
+            hit = None
+        if hit and isinstance(hit.get("result"), dict) and hit["result"]:
+            # Serving from cache skips route_pre_answer (and thus the cognitive
+            # source's process_queue=True). Don't lose memory-observation
+            # ingestion just because we hit the cache: process the queue
+            # directly on the hit turn. Bounded, best-effort, never blocks the
+            # answer — failures are swallowed.
+            try:
+                from memory_retrieval import process_memory_observation_queue
+
+                process_memory_observation_queue(limit=50)
+            except Exception:
+                pass
+            cached_result = dict(hit["result"])
+            cached_result["cache_hit"] = True
+            cached_result["resolution_cache"] = {
+                "cache_key": policy.route_cache_key,
+                "hit": True,
+                "resolved_at": hit.get("resolved_at"),
+                "expires_at": hit.get("expires_at"),
+                "hit_count": hit.get("hit_count"),
+            }
+            try:
+                from local_context.usage_events import record_router_usage
+
+                cached_result["usage_event"] = record_router_usage(
+                    query,
+                    cached_result,
+                    client=str(payload.get("source") or payload.get("client") or "unknown"),
+                    tool="pre_answer_router",
+                    route_stage="pre_answer",
+                    intent=str(cached_result.get("intent") or policy.intent or "auto"),
+                    elapsed_ms=0,
+                    deadline_ms=int(cached_result.get("deadline_ms") or policy.deadline_ms),
+                    used_before_response=True,
+                    cache_hit=True,
+                )
+            except Exception:
+                pass
+            return cached_result
+
     result = _run_with_policy(
         query=query,
         payload=payload,
@@ -524,6 +648,36 @@ def run_pre_answer_route(
         result["escalated_from"] = policy.budget_tier
         result["escalated_to"] = escalated_policy.budget_tier
 
+    # ── SET: cache the FINAL result (post-escalation), never mid-way ──────
+    # Only cache real, source-backed answers: an empty/no-evidence pass should
+    # not poison the cache (it would mask a future genuine resolution). The
+    # 'instant' tier and missing key are rejected inside resolution_cache.set.
+    result["cache_hit"] = False
+    if cache_enabled and (result.get("should_inject") or result.get("evidence_refs")):
+        try:
+            import resolution_cache
+
+            set_outcome = resolution_cache.set(
+                policy.route_cache_key,
+                result,
+                ttl_seconds=int(policy.cache_ttl_seconds),
+                kind="route",
+                intent=str(policy.intent or ""),
+                area=str(payload.get("area") or ""),
+                sid=sid if policy.intent in resolution_cache.SESSION_SCOPED_INTENTS else "",
+                source_refs=result.get("evidence_refs"),
+                policy_version=str(policy.policy_version or ""),
+            )
+            result["resolution_cache"] = {
+                "cache_key": policy.route_cache_key,
+                "hit": False,
+                "stored": bool(set_outcome.get("ok")),
+                "store_reason": set_outcome.get("reason", ""),
+                "expires_at": set_outcome.get("expires_at"),
+            }
+        except Exception:
+            pass
+
     try:
         from local_context.usage_events import record_router_usage
 
@@ -537,6 +691,7 @@ def run_pre_answer_route(
             elapsed_ms=int(float(result.get("elapsed_ms") or 0)),
             deadline_ms=int(result.get("deadline_ms") or policy.deadline_ms),
             used_before_response=True,
+            cache_hit=False,
         )
     except Exception as exc:
         result["usage_event"] = {