ltcai 10.10.0 → 11.1.0

package/lattice_brain/graph/fusion.py

@@ -28,7 +28,7 @@ from __future__ import annotations
 import json
 import os
 import re
-from typing import Any, Dict, Mapping, Optional
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple
 
 from ..quiet import quiet
 
@@ -36,6 +36,26 @@ QUERY_CLASSES = ("fact", "code", "person", "recency")
 
 FUSION_WEIGHTS_ENV = "LATTICEAI_FUSION_WEIGHTS"
 
+# ── fusion strategy (v11.1.0) ────────────────────────────────────────────────
+# Linear alpha fusion needs the two channels' scores to be comparable. They
+# are not: the lexical channel scores 1/rank while the vector channel scores a
+# max-normalized cosine, so a query where every cosine lands near 0.9 flattens
+# the vector channel to noise. Reciprocal Rank Fusion ignores score magnitudes
+# entirely and fuses *positions*, which is exactly the property that survives
+# incomparable scales.
+#
+# It is opt-in, per query class, and off everywhere by default: alpha fusion
+# is what every existing ranking assertion in this repo describes, and a
+# ranking change dressed up as a bug fix is how retrieval quality regressions
+# get shipped. Turn it on with LATTICEAI_FUSION_STRATEGY=rrf (all classes) or
+# a JSON object like {"code": "rrf"} (per class).
+FUSION_STRATEGY_ENV = "LATTICEAI_FUSION_STRATEGY"
+FUSION_STRATEGIES = ("alpha", "rrf")
+DEFAULT_FUSION_STRATEGY: Dict[str, str] = dict.fromkeys(QUERY_CLASSES, "alpha")
+#: The smoothing constant from the original RRF paper (Cormack et al., 2009).
+#: Larger k flattens the curve, so rank 1 wins by less.
+DEFAULT_RRF_K = 60
+
 # Per-class fusion weights. "fact" mirrors the pre-fusion-gate defaults
 # (SearchService DEFAULT_HYBRID_WEIGHTS + graph-layer alpha=0.6) so the
 # fallback class introduces zero behavioral drift.
@@ -145,16 +165,163 @@ def fusion_weight_table(
     return table
 
 
+def _env_strategy_overrides() -> Dict[str, str]:
+    """Parse ``LATTICEAI_FUSION_STRATEGY`` → per-class strategy overrides.
+
+    Two accepted forms: a bare strategy name (``rrf``) applies to every class,
+    a JSON object (``{"code": "rrf"}``) applies per class. Anything else —
+    a typo, malformed JSON, an unknown strategy — is ignored rather than
+    raising, so a bad env var degrades to the default fusion instead of
+    taking every search down.
+    """
+    raw = os.getenv(FUSION_STRATEGY_ENV, "").strip()
+    if not raw:
+        return {}
+    if raw.lower() in FUSION_STRATEGIES:
+        return dict.fromkeys(QUERY_CLASSES, raw.lower())
+    try:
+        payload = json.loads(raw)
+    except (ValueError, TypeError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return {
+        str(cls): str(value).lower()
+        for cls, value in payload.items()
+        if cls in DEFAULT_FUSION_STRATEGY and str(value).lower() in FUSION_STRATEGIES
+    }
+
+
+def fusion_strategy_table(
+    overrides: Optional[Mapping[str, str]] = None,
+) -> Dict[str, str]:
+    """Full per-class strategy table: defaults ← env override ← caller."""
+    table = dict(DEFAULT_FUSION_STRATEGY)
+    for source in (_env_strategy_overrides(), overrides or {}):
+        for cls, value in source.items():
+            if cls in table and str(value).lower() in FUSION_STRATEGIES:
+                table[cls] = str(value).lower()
+    return table
+
+
+def rrf_score(rank: int, *, k: int = DEFAULT_RRF_K) -> float:
+    """One channel's contribution for an item it ranked at ``rank`` (1-based)."""
+    return 1.0 / (int(k) + max(1, int(rank)))
+
+
+def rrf_fuse(
+    rankings: Mapping[str, Sequence[str]],
+    *,
+    k: int = DEFAULT_RRF_K,
+    weights: Optional[Mapping[str, float]] = None,
+) -> Dict[str, float]:
+    """Reciprocal Rank Fusion over per-channel id rankings.
+
+    ``rankings`` maps a channel name to its ids in rank order (best first).
+    An id absent from a channel simply contributes nothing from it — RRF has
+    no notion of a "missing score" to guess at, which is the other reason it
+    survives channels that fail independently.
+
+    ``weights`` optionally scales a channel's contribution (a channel missing
+    from the mapping weighs 1.0). Deterministic and pure.
+    """
+    fused: Dict[str, float] = {}
+    for channel, ordered in rankings.items():
+        weight = 1.0 if weights is None else float(weights.get(channel, 1.0))
+        for rank, item_id in enumerate(ordered, start=1):
+            fused[item_id] = fused.get(item_id, 0.0) + weight * rrf_score(rank, k=k)
+    return fused
+
+
+# ── graph traversal candidate expansion (v11.1.0) ────────────────────────────
+# Both retrieval channels can only return what they matched. A note that
+# never says "postgres" but is one CONTAINS edge away from the one that does
+# is unreachable by either — and it is often the answer. Expansion walks one
+# hop out from the top hits and offers those neighbours as candidates.
+#
+# It is capped, off by default, and reports its own counts, because the
+# failure mode is dilution: an unbounded expansion turns a precise answer into
+# a tour of the graph.
+GRAPH_EXPANSION_ENV = "LATTICEAI_GRAPH_EXPANSION"
+DEFAULT_EXPANSION_SEEDS = 3
+DEFAULT_EXPANSION_CAP = 5
+#: Expanded candidates inherit a damped share of their seed's score: they are
+#: related to a hit, they are not themselves a hit.
+EXPANSION_DECAY = 0.5
+
+
+def graph_expansion_enabled() -> bool:
+    """True when ``LATTICEAI_GRAPH_EXPANSION`` opts in (default: off)."""
+    raw = os.getenv(GRAPH_EXPANSION_ENV, "").strip().lower()
+    return raw in {"1", "true", "yes", "on"}
+
+
+def expand_with_neighbors(
+    seeds: Sequence[Tuple[str, float]],
+    neighbors_fn: Callable[[str], Any],
+    *,
+    exclude: Optional[Sequence[str]] = None,
+    cap: int = DEFAULT_EXPANSION_CAP,
+) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+    """One-hop neighbours of ``seeds`` as extra candidates + an honest report.
+
+    ``seeds`` is ``[(node_id, score)]`` best first; ``neighbors_fn`` is the
+    store's ``neighbors``. Returns ``(candidates, report)`` where each
+    candidate carries its originating seed and a decayed score, and the report
+    states how many seeds were walked, how many candidates were kept, and
+    whether the cap bit. A neighbour lookup that fails is skipped and counted,
+    never raised: expansion is an optimization, not a dependency.
+    """
+    known = {str(item) for item in (exclude or ())}
+    cap = max(0, int(cap))
+    candidates: List[Dict[str, Any]] = []
+    failures = 0
+    for seed_id, seed_score in seeds:
+        if len(candidates) >= cap:
+            break
+        try:
+            payload = neighbors_fn(seed_id) or {}
+        except Exception:  # noqa: BLE001 — a bad seed must not fail the search
+            failures += 1
+            continue
+        for node in payload.get("neighbors") or []:
+            node_id = str(node.get("id") or "")
+            if not node_id or node_id in known:
+                continue
+            known.add(node_id)
+            candidates.append(
+                {
+                    "node": node,
+                    "seed": str(seed_id),
+                    "score": round(float(seed_score) * EXPANSION_DECAY, 6),
+                }
+            )
+            if len(candidates) >= cap:
+                break
+    report = {
+        "enabled": True,
+        "seeds": len(seeds),
+        "added": len(candidates),
+        "cap": cap,
+        "truncated": len(candidates) >= cap,
+        "failed_seeds": failures,
+    }
+    return candidates, report
+
+
 def fusion_profile(
     query: Any,
     *,
     overrides: Optional[Mapping[str, Mapping[str, float]]] = None,
+    strategies: Optional[Mapping[str, str]] = None,
 ) -> Dict[str, Any]:
     """Classify ``query`` and return its resolved fusion weights.
 
     Returns ``{"query_class": str, "weights": {keyword, vector, graph},
-    "alpha": float}``. ``weights`` feeds the three-channel service fusion;
-    ``alpha`` feeds the two-channel graph-layer fusion.
+    "alpha": float, "strategy": "alpha"|"rrf"}``. ``weights`` feeds the
+    three-channel service fusion; ``alpha`` feeds the two-channel graph-layer
+    fusion; ``strategy`` selects *how* those channels combine and is
+    ``"alpha"`` for every class unless configured otherwise.
     """
     query_class = classify_query(query)
     table = fusion_weight_table(overrides)
@@ -170,14 +337,28 @@ def fusion_profile(
             "graph": resolved["graph"],
         },
         "alpha": resolved["alpha"],
+        "strategy": fusion_strategy_table(strategies)[query_class],
     }
 
 
 __all__ = [
+    "DEFAULT_EXPANSION_CAP",
+    "DEFAULT_EXPANSION_SEEDS",
+    "DEFAULT_FUSION_STRATEGY",
     "DEFAULT_FUSION_WEIGHTS",
+    "DEFAULT_RRF_K",
+    "EXPANSION_DECAY",
+    "FUSION_STRATEGIES",
+    "FUSION_STRATEGY_ENV",
     "FUSION_WEIGHTS_ENV",
+    "GRAPH_EXPANSION_ENV",
     "QUERY_CLASSES",
     "classify_query",
+    "expand_with_neighbors",
     "fusion_profile",
+    "fusion_strategy_table",
     "fusion_weight_table",
+    "graph_expansion_enabled",
+    "rrf_fuse",
+    "rrf_score",
 ]

package/lattice_brain/graph/image_vectors.py

@@ -0,0 +1,230 @@
+"""The image vector space — stored apart, joined by late fusion (v11.1.0).
+
+A CLIP image vector and a BGE text vector are both "1024 floats", and that is
+the entire extent of what they have in common. Filing them in one index means
+every cosine between them is a number with no meaning, and the ranking that
+comes out looks exactly like a working search.
+
+So image vectors get their own table (``image_embeddings``) keyed by the vision
+model that produced them, and their own search. Text queries never touch this
+index: they reach pictures through OCR text and captions, which are text and
+live in the text index like everything else. This index answers one question —
+*which stored images look like this vector* — and its scores enter
+``hybrid_search`` by late fusion, as a separate channel with its own weight,
+rather than by pretending to be comparable up front.
+
+The table is created on demand, is derivable from the images themselves, and is
+never the source of truth: dropping it costs a re-embed, not a memory.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import struct
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from .vector_index import build_index, resolve_vector_index
+
+IMAGE_VECTOR_TABLE = "image_embeddings"
+#: Default weight the image channel carries when fused with text scores.
+DEFAULT_IMAGE_FUSION_WEIGHT = 0.5
+
+
+def ensure_image_vector_table(conn: sqlite3.Connection) -> None:
+    """Create the image-vector table if this graph has never held one."""
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {IMAGE_VECTOR_TABLE} (
+            node_id TEXT PRIMARY KEY,
+            model_id TEXT NOT NULL,
+            dim INTEGER NOT NULL,
+            space TEXT NOT NULL DEFAULT 'image',
+            vector BLOB NOT NULL,
+            updated_at TEXT
+        )
+        """
+    )
+
+
+def encode_vector(vector: Sequence[float]) -> bytes:
+    values = [float(value) for value in vector]
+    return struct.pack(f"<{len(values)}f", *values)
+
+
+def decode_vector(payload: bytes) -> List[float]:
+    count = len(payload) // 4
+    return list(struct.unpack(f"<{count}f", payload[: count * 4]))
+
+
+def record_image_vector(
+    store: Any,
+    *,
+    node_id: str,
+    vector: Sequence[float],
+    model_id: str,
+    space: str = "image",
+    updated_at: Optional[str] = None,
+) -> bool:
+    """Persist one image vector. Returns False when there is nothing to store.
+
+    Never raises: an image whose vector could not be filed is still a memory,
+    and :func:`image_index_status` reports it as backlog.
+    """
+    values = [float(value) for value in (vector or [])]
+    if not node_id or not values or not model_id:
+        return False
+    try:
+        with store._connect() as conn:
+            ensure_image_vector_table(conn)
+            conn.execute(
+                f"""
+                INSERT INTO {IMAGE_VECTOR_TABLE}
+                    (node_id, model_id, dim, space, vector, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+                ON CONFLICT(node_id) DO UPDATE SET
+                    model_id=excluded.model_id,
+                    dim=excluded.dim,
+                    space=excluded.space,
+                    vector=excluded.vector,
+                    updated_at=excluded.updated_at
+                """,
+                (
+                    str(node_id),
+                    str(model_id),
+                    len(values),
+                    str(space or "image"),
+                    encode_vector(values),
+                    updated_at,
+                ),
+            )
+        return True
+    except Exception:  # noqa: BLE001 — a vector is derivable; the image is not
+        return False
+
+
+def _rows(
+    store: Any, model_id: Optional[str], dim: Optional[int]
+) -> List[Tuple[str, List[float]]]:
+    with store._connect() as conn:
+        ensure_image_vector_table(conn)
+        if model_id:
+            cursor = conn.execute(
+                f"SELECT node_id, vector, dim FROM {IMAGE_VECTOR_TABLE} WHERE model_id=? ORDER BY node_id ASC",
+                (str(model_id),),
+            )
+        else:
+            cursor = conn.execute(
+                f"SELECT node_id, vector, dim FROM {IMAGE_VECTOR_TABLE} ORDER BY node_id ASC"
+            )
+        rows = cursor.fetchall()
+    out: List[Tuple[str, List[float]]] = []
+    for row in rows:
+        if dim is not None and int(row["dim"]) != dim:
+            # A different width means a different model. Comparing across it is
+            # the exact silent wrongness this whole module exists to prevent.
+            continue
+        out.append((str(row["node_id"]), decode_vector(row["vector"])))
+    return out
+
+
+def image_similarity_search(
+    store: Any,
+    vector: Sequence[float],
+    *,
+    top_k: int = 10,
+    model_id: Optional[str] = None,
+    min_score: float = 0.0,
+) -> Dict[str, Any]:
+    """Rank stored images against a query *image* vector.
+
+    Scoring is delegated to the pluggable backend layer (Track 1), so this
+    index picks up ``LATTICEAI_VECTOR_INDEX`` and reports the same
+    ``approx``/``exhaustive`` honesty bits as the text index.
+    """
+    query = [float(value) for value in (vector or [])]
+    result: Dict[str, Any] = {
+        "matches": [],
+        "count": 0,
+        "candidates": 0,
+        "model_id": model_id,
+        "detail": None,
+    }
+    if not query:
+        result["detail"] = "an image query needs an image vector"
+        return result
+    try:
+        rows = _rows(store, model_id, len(query))
+    except Exception as exc:  # noqa: BLE001 — degrade, never fail the search
+        result["detail"] = f"image vector index unavailable: {exc}"
+        return result
+    result["candidates"] = len(rows)
+    selection = resolve_vector_index()
+    index = build_index(selection, dim=len(query))
+    index.rebuild((node_id, values, {}) for node_id, values in rows)
+    scored = index.search(query, max(1, int(top_k)), {"min_score": min_score})
+    result["matches"] = [
+        {"node_id": node_id, "score": round(float(score), 6)} for node_id, score in scored
+    ]
+    result["count"] = len(result["matches"])
+    result["index"] = selection.as_dict()
+    return result
+
+
+def image_index_status(store: Any) -> Dict[str, Any]:
+    """How many images carry a vector, and under which model."""
+    status: Dict[str, Any] = {"vectors": 0, "models": {}, "detail": None}
+    try:
+        with store._connect() as conn:
+            ensure_image_vector_table(conn)
+            rows = conn.execute(
+                f"SELECT model_id, COUNT(*) AS total FROM {IMAGE_VECTOR_TABLE} GROUP BY model_id"
+            ).fetchall()
+    except Exception as exc:  # noqa: BLE001 — status must never raise
+        status["detail"] = str(exc)
+        return status
+    models = {str(row["model_id"]): int(row["total"]) for row in rows}
+    status["models"] = models
+    status["vectors"] = sum(models.values())
+    return status
+
+
+def fuse_image_scores(
+    matches: Iterable[Dict[str, Any]],
+    image_scores: Dict[str, float],
+    *,
+    weight: float = DEFAULT_IMAGE_FUSION_WEIGHT,
+) -> int:
+    """Late-fuse image-space scores into an already-fused match list.
+
+    Mutates each match in place — ``scores.image`` records the raw image-space
+    similarity and ``score`` blends it in — and returns how many matches the
+    image channel actually touched. Late fusion is the point: the two spaces
+    are ranked separately and combined at the end, so neither is ever asked to
+    interpret the other's numbers.
+    """
+    weight = max(0.0, min(1.0, float(weight)))
+    touched = 0
+    for match in matches:
+        node_id = str(match.get("node_id") or "")
+        raw = image_scores.get(node_id)
+        if raw is None:
+            continue
+        touched += 1
+        scores = match.setdefault("scores", {})
+        scores["image"] = round(float(raw), 6)
+        blended = (1.0 - weight) * float(match.get("score") or 0.0) + weight * float(raw)
+        match["score"] = round(blended, 6)
+    return touched
+
+
+__all__ = [
+    "DEFAULT_IMAGE_FUSION_WEIGHT",
+    "IMAGE_VECTOR_TABLE",
+    "decode_vector",
+    "encode_vector",
+    "ensure_image_vector_table",
+    "fuse_image_scores",
+    "image_index_status",
+    "image_similarity_search",
+    "record_image_vector",
+]

package/lattice_brain/graph/ingest.py

@@ -636,14 +636,20 @@ class KnowledgeGraphIngestMixin(_Core):
         modified_at: Optional[str] = None,
         conversation_id: Optional[str] = None,
         metadata: Optional[Dict[str, Any]] = None,
+        node_type: str = "Document",
     ) -> Dict[str, Any]:
         """Unified text/web ingestion: one shape for URL, browser tab, note, text.
 
-        Creates a content ``Document`` node (idempotent by content hash), a
-        ``Source`` node linked via ``indexed_from``, RAG chunks, and extracted
+        Creates a content node (idempotent by content hash), a ``Source`` node
+        linked via ``indexed_from``, RAG chunks, and extracted
         Concept/Task/Decision nodes — mirroring ingest_document for non-file
         sources. Returns the full set of ids the caller needs to record
         provenance, including ``duplicate`` (was the content already indexed).
+
+        ``node_type`` names the content node. It defaults to ``Document``, so
+        every historical caller is unchanged; a door that knows its material is
+        something else (``Audio`` for a recording) says so here rather than
+        writing a second ingest path to say it.
         """
         source_type = str(source_type or "text")
         text = str(text or "")
@@ -674,11 +680,11 @@ class KnowledgeGraphIngestMixin(_Core):
 
         with self._connect() as conn:
             duplicate = self._node_exists(conn, content_id)
-            # ── 콘텐츠 노드 (점: 명사 — 문서) ────────────────────────────────
+            # ── 콘텐츠 노드 (점: 명사 — 기본은 문서) ─────────────────────────
             self._upsert_node(
                 conn,
                 content_id,
-                "Document",
+                node_type,
                 title,
                 summary=(text or title)[:500],
                 metadata=node_meta,
@@ -813,7 +819,7 @@ class KnowledgeGraphIngestMixin(_Core):
 
         return {
             "node_id": content_id,
-            "type": "Document",
+            "type": node_type,
             "source_node_id": source_node_id,
             "content_hash": content_hash,
             "chunk_ids": chunk_ids,

package/lattice_brain/graph/proactive.py

@@ -48,6 +48,21 @@ _DEFAULT_CONTRADICTION_NODES = 300
 _DEFAULT_NEAR_THRESHOLD = 0.75
 _DEFAULT_MAX_PAIRS = 200
 _DEFAULT_STALE_DAYS = 90  # mirrors MemoryQualityManager.apply_retention
+_DEFAULT_HALF_LIFE_DAYS = 30.0
+# Node types that record *what happened* rather than *what is known*. Only
+# these are offered for consolidation: folding a Decision or a Document into a
+# summary would lose the thing the user actually keeps a Brain for.
+_EPISODIC_TYPES = frozenset(
+    {
+        "chat",
+        "conversation",
+        "message",
+        "airesponse",
+        "ai_response",
+        "event",
+        "chunk",
+    }
+)
 
 
 def _parse_ts(value: Any) -> Optional[datetime]:
@@ -78,6 +93,28 @@ def _node_text(node: Dict[str, Any]) -> str:
     return f"{title} {summary}".strip()
 
 
+def _is_episodic(node: Dict[str, Any]) -> bool:
+    return str(node.get("type") or "").strip().lower() in _EPISODIC_TYPES
+
+
+def _access_count(node: Dict[str, Any], stored: Optional[Dict[str, Any]]) -> float:
+    """Access count for a node: ingested metadata first, then the store counter.
+
+    A surface that already tracks reads (``metadata.access_count``) is more
+    accurate than our own read-path counter, so it wins; ``0`` from metadata is
+    a real answer and is not treated as "missing".
+    """
+    metadata = node.get("metadata")
+    if isinstance(metadata, dict):
+        for key in ("access_count", "accesses", "access"):
+            value = metadata.get(key)
+            if isinstance(value, (int, float)) and not isinstance(value, bool):
+                return float(value)
+    if stored is None:
+        return 0.0
+    return float(stored.get("accesses") or 0.0)
+
+
 def _slim(node: Dict[str, Any]) -> Dict[str, Any]:
     return {
         "id": node.get("id"),
@@ -129,6 +166,17 @@ class ProactiveBrain:
             edges.append(normalized)
         return {"nodes": nodes, "edges": edges}
 
+    def sample(
+        self, *, workspace_id: Optional[str] = None, limit: Optional[int] = None
+    ) -> Dict[str, List[Dict[str, Any]]]:
+        """One normalized graph sample (``source``/``target`` edge keys).
+
+        Public seam for :mod:`lattice_brain.synthesis`, which needs the *same*
+        sample for several passes; taking it once keeps a synthesis run to one
+        graph read and keeps every pass looking at identical data.
+        """
+        return self._sample(workspace_id=workspace_id, limit=limit)
+
     # ── duplicates ───────────────────────────────────────────────────────
 
     def find_duplicates(
@@ -246,6 +294,16 @@ class ProactiveBrain:
             sample["nodes"], sample["edges"], max_nodes=max_nodes
         )
 
+    def contradictions_in(
+        self,
+        nodes: List[Dict[str, Any]],
+        edges: List[Dict[str, Any]],
+        *,
+        max_nodes: int = _DEFAULT_CONTRADICTION_NODES,
+    ) -> Dict[str, Any]:
+        """Contradiction signals over an already-taken :meth:`sample`."""
+        return self._detect_contradictions_in(nodes, edges, max_nodes=max_nodes)
+
     def _detect_contradictions_in(
         self,
         nodes: List[Dict[str, Any]],
@@ -403,6 +461,85 @@ class ProactiveBrain:
             "generated_at": datetime.now(timezone.utc).isoformat(),
         }
 
+    # ── importance & decay (v11.1.0) ─────────────────────────────────────
+
+    def importance_report(
+        self,
+        *,
+        workspace_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        half_life_days: float = _DEFAULT_HALF_LIFE_DAYS,
+        max_candidates: int = 20,
+        sample: Optional[Dict[str, List[Dict[str, Any]]]] = None,
+    ) -> Dict[str, Any]:
+        """Score every sampled node by use, then name the weakest episodic ones.
+
+        The score is deliberately boring and reproducible — no model, no
+        randomness::
+
+            score = (1 + accesses + degree) * 0.5 ** (age_days / half_life)
+
+        *accesses* prefers a real counter: ``metadata.access_count`` when the
+        ingesting surface recorded one, otherwise the store's own read-path
+        counter (``access_stats``), otherwise zero. *Episodic* types (chats,
+        messages, events, chunks) are the only consolidation candidates —
+        a decayed Document or Decision is stale knowledge to review, not
+        noise to fold away.
+        """
+        data = sample if sample is not None else self._sample(
+            workspace_id=workspace_id, limit=limit
+        )
+        nodes, edges = data["nodes"], data["edges"]
+        degree: Dict[str, int] = {}
+        for edge in edges:
+            for key in ("source", "target"):
+                node_id = str(edge.get(key) or "")
+                if node_id:
+                    degree[node_id] = degree.get(node_id, 0) + 1
+
+        stats_fn = getattr(self._store, "access_stats", None)
+        stored: Dict[str, Any] = {}
+        if callable(stats_fn):
+            try:
+                stored = dict(stats_fn([n.get("id") for n in nodes]) or {})
+            except Exception:  # noqa: BLE001 — the report degrades, never fails
+                logger.exception("access stats read failed")
+
+        now = datetime.now(timezone.utc)
+        half_life = max(0.5, float(half_life_days))
+        scored: List[Dict[str, Any]] = []
+        for node in nodes:
+            node_id = str(node.get("id") or "")
+            accesses = _access_count(node, stored.get(node_id))
+            ts = _parse_ts(node.get("updated_at"))
+            age_days = 0.0 if ts is None else max(
+                0.0, (now - ts).total_seconds() / 86400.0
+            )
+            decay = 0.5 ** (age_days / half_life)
+            scored.append(
+                {
+                    **_slim(node),
+                    "accesses": accesses,
+                    "degree": degree.get(node_id, 0),
+                    "age_days": round(age_days, 2),
+                    "score": round((1.0 + accesses + degree.get(node_id, 0)) * decay, 4),
+                    "episodic": _is_episodic(node),
+                }
+            )
+        scored.sort(key=lambda item: (item["score"], str(item.get("id") or "")))
+        candidates = [item for item in scored if item["episodic"]][
+            : max(1, int(max_candidates))
+        ]
+        return {
+            "nodes_scanned": len(nodes),
+            "half_life_days": half_life,
+            "access_source": "store" if stored else "metadata",
+            "candidates": candidates,
+            "candidate_count": len(candidates),
+            "strongest": list(reversed(scored[-5:])),
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+        }
+
     # ── consolidation ────────────────────────────────────────────────────
 
     def consolidate_duplicates(
@@ -470,7 +607,7 @@ class ProactiveBrain:
             for group in groups:
                 try:
                     if merge_fn is None:  # guarded by apply_supported above
-                        raise RuntimeError("store has no merge_nodes")
+                        raise RuntimeError("store has no merge_nodes")  # pragma: no cover — unreachable: callable(merge_fn) above proves it is not None
                     result = merge_fn(group["keep"], group["remove"])
                     applied.append({"keep": group["keep"], "result": result})
                 except Exception as exc:  # keep going; report per-group failure