superlocalmemory 4.1.13 → 4.1.15

package/src/superlocalmemory/server/routes/memories.py

@@ -1,1661 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-"""SuperLocalMemory V3 - Memory Routes (AGPL-3.0-or-later).
-Routes: /api/memories, /api/graph, /api/search, /api/clusters, /api/clusters/{id}
-Uses V3 MemoryEngine for store/recall. Falls back to direct DB for list/graph.
-"""
-import json
-import logging
-import re
-import uuid
-from typing import Optional
-
-from fastapi import APIRouter, HTTPException, Query, Request
-
-from superlocalmemory.core.config import BROWSE_PAGE_SIZE
-from superlocalmemory.storage.database import (
-    visible_fact_clause_for_connection,
-)
-
-from .helpers import (
-    SearchRequest,
-    dict_factory,
-    get_active_profile,
-    get_db_connection,
-    get_engine_lazy,
-)
-
-logger = logging.getLogger("superlocalmemory.routes.memories")
-router = APIRouter()
-_IDEMPOTENCY_KEY = re.compile(r"^[A-Za-z0-9._:-]{1,256}$")
-
-# v3.8.3: GENEROUS latency budget for recall. SLM's value is quality recall
-# under heavy multi-agent load, so semantic recall is given ample time to
-# finish — the keyword fallback is a LAST-RESORT safety net for a genuine hang
-# (e.g. a wedged embedder), NOT an aggressive speed cutoff. Only if recall
-# exceeds this budget do we serve the fast keyword search so the caller ALWAYS
-# gets a result instead of hanging forever. Tune with SLM_SEARCH_RECALL_TIMEOUT_S.
-# The dashboard's fetch timeout is set ABOVE this so the browser waits for the
-# quality result rather than aborting early.
-_DEFAULT_RECALL_BUDGET_S = 25.0
-
-
-def _search_recall_timeout_s() -> float:
-    import os
-    try:
-        v = float(os.environ.get("SLM_SEARCH_RECALL_TIMEOUT_S", ""))
-        return v if v > 0 else _DEFAULT_RECALL_BUDGET_S
-    except (TypeError, ValueError):
-        return _DEFAULT_RECALL_BUDGET_S
-
-
-def _internal_error(detail: str = "Internal server error") -> HTTPException:
-    """SEC-H-02: log the full traceback server-side; return a generic message.
-
-    Returning ``str(e)`` to HTTP clients leaks DB schema (column/constraint
-    names), the data-directory filesystem path, and possibly config internals —
-    a GDPR Art. 32 gap. Call this only from inside an ``except`` block so
-    ``logger.exception`` captures the active traceback automatically.
-    """
-    logger.exception("memories route error")
-    return HTTPException(status_code=500, detail=detail)
-
-
-def _get_engine(request: Request):
-    """Get V3 engine from app state, initializing lazily on first call."""
-    return get_engine_lazy(request.app.state)
-
-
-def _canonical_mutation_runtime(request: Request):
-    """Return the daemon-owned mutation boundary or fail before queueing work."""
-    runtime = getattr(request.app.state, "canonical_remember_runtime", None)
-    if runtime is None or not runtime.ready:
-        raise HTTPException(503, detail="canonical mutation writer is not ready; retry shortly")
-    return runtime
-
-
-def _mutation_idempotency_key(request: Request) -> str:
-    """Accept a client retry key without making one mandatory for the dashboard."""
-    key = request.headers.get("X-Idempotency-Key", "").strip() or str(uuid.uuid4())
-    if not _IDEMPOTENCY_KEY.fullmatch(key):
-        raise HTTPException(
-            422,
-            detail="X-Idempotency-Key must contain 1-256 safe characters",
-        )
-    return key
-
-
-def _canonical_mutation_error(exc: Exception, detail: str) -> HTTPException:
-    """Map typed mutation failures without leaking SQLite or filesystem detail."""
-    from superlocalmemory.core.remember_runtime import (
-        CanonicalMutationConflict,
-        CanonicalRememberUnavailable,
-    )
-
-    if isinstance(exc, CanonicalMutationConflict):
-        return HTTPException(409, detail=str(exc))
-    if isinstance(exc, CanonicalRememberUnavailable):
-        return HTTPException(
-            503,
-            detail="canonical mutation writer is temporarily unavailable",
-        )
-    return _internal_error(detail)
-
-
-def _mutation_runtime_or_missing_fact(
-    request: Request, engine, profile_id: str, fact_id: str,
-):
-    """Retain the public 404 for a missing fact without creating a local writer."""
-    runtime = getattr(request.app.state, "canonical_remember_runtime", None)
-    if runtime is not None and runtime.ready:
-        return runtime
-    rows = engine._db.execute(
-        "SELECT 1 FROM atomic_facts WHERE fact_id = ? AND profile_id = ?",
-        (fact_id, profile_id),
-    )
-    if not rows:
-        raise HTTPException(status_code=404, detail="Memory not found")
-    raise HTTPException(503, detail="canonical mutation writer is not ready; retry shortly")
-
-
-def _admit_http_mutation(request: Request, operation: str) -> None:
-    """Route a memory HTTP mutation through OperationPolicyRegistry.evaluate().
-
-    Called from _authorize_memory_mutation after RBAC passes. Raises HTTP 403
-    if the policy registry denies the actor. Maps "delete" → FORGET,
-    "update" → CORRECT. Uses the server-derived principal and roles.
-    """
-    from fastapi import HTTPException as _HTTPException
-
-    from superlocalmemory.core.actor_context import Transport
-    from superlocalmemory.core.admission import AdmissionDenied, admit, resolve_actor
-    from superlocalmemory.core.operation_request import OperationKind
-    from superlocalmemory.server.rbac_enforce import (
-        resolve_actor_roles,
-        resolve_principal,
-    )
-
-    from superlocalmemory.core.admission import _company_mode_active
-
-    # Both switches, the same rule the other entry points use. Reading
-    # config.toml alone left this path treating a workspace as personal after
-    # the dashboard toggle had turned per-user access on -- so a write refused
-    # everywhere else was admitted here.
-    deployment = getattr(request.app.state, "deployment", None)
-    if deployment is None:
-        from superlocalmemory.core.admission import _resolve_deployment
-
-        deployment = _resolve_deployment()
-    company = _company_mode_active(deployment)
-    tier = "enterprise" if company else "personal"
-    mode = "company" if company else "local"
-
-    principal_info = resolve_principal(request)
-    principal = str(principal_info.get("user_id") or "")
-    actor_roles = resolve_actor_roles(request)
-    actor = resolve_actor(
-        Transport.HTTP,
-        tier=tier,
-        mode=mode,
-        principal=principal,
-        roles=actor_roles,
-    )
-    kind = OperationKind.FORGET if operation == "delete" else OperationKind.CORRECT
-    try:
-        admit(kind, actor, mode=mode)
-    except AdmissionDenied as exc:
-        raise _HTTPException(
-            status_code=403,
-            detail=f"Operation denied: {exc.decision.reason}",
-        ) from exc
-
-
-def _authorize_memory_mutation(
-    request: Request,
-    operation: str,
-    fact_id: str,
-    *,
-    content_preview: str = "",
-    run_pre_hook: bool = True,
-):
-    """Authenticate a mutation, optionally gating route-owned direct SQL."""
-    from superlocalmemory.server.write_identity import require_write_actor
-
-    actor_id = require_write_actor(
-        request,
-        getattr(request.app.state, "daemon_descriptor", None),
-        actor_kind="dashboard",
-    )
-    # RBAC (C3): on top of machine auth, enforce the caller's role on the active
-    # profile. delete → DELETE; every other mutation → WRITE.
-    from superlocalmemory.access.rbac import Permission as _Perm
-    from superlocalmemory.server.rbac_enforce import require_permission as _rbac_require
-    _rbac_require(
-        request,
-        _Perm.DELETE if operation == "delete" else _Perm.WRITE,
-    )
-    # Phase 1: admission gateway — policy registry decision for this route.
-    _admit_http_mutation(request, operation)
-    engine = _get_engine(request)
-    if engine is None:
-        raise HTTPException(503, detail="Engine not initialized")
-    profile_id = engine.profile_id
-    context = {
-        "operation": operation,
-        "agent_id": actor_id,
-        "source_agent_id": "dashboard",
-        "profile_id": profile_id,
-        "fact_id": fact_id,
-    }
-    if content_preview:
-        context["content_preview"] = content_preview[:100]
-    if run_pre_hook:
-        try:
-            engine._hooks.run_pre(operation, context)
-        except Exception as exc:
-            logger.warning("Dashboard %s authorization rejected: %s", operation, exc)
-            raise HTTPException(403, detail="Write authorization rejected") from exc
-    return engine, profile_id, context
-
-
-def _preview(content: str | None) -> str:
-    """Truncate content for preview display."""
-    if not content:
-        return ""
-    return content[:100] + "..." if len(content) > 100 else content
-
-
-def _has_table(cursor, name: str) -> bool:
-    """Check if a table exists in the database."""
-    try:
-        cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name=?", (name,))
-        return cursor.fetchone() is not None
-    except Exception:
-        return False
-
-
-def _fetch_graph_data(
-    cursor, profile: str, use_v3: bool, min_importance: int, max_nodes: int,
-) -> tuple[list, list, list]:
-    """Fetch graph nodes, links, clusters from V3 or V2 schema."""
-    if use_v3:
-        # Recency-first: get the most recent nodes, then find their edges.
-        # LEFT JOIN fact_importance for graph metrics (v3.4.1 — additive only).
-        cursor.execute("""
-            SELECT af.fact_id as id, af.content, af.fact_type as category,
-                   af.confidence as importance, af.session_id as project_name,
-                   af.created_at,
-                   fi.pagerank_score, fi.community_id, fi.degree_centrality
-            FROM atomic_facts af
-            LEFT JOIN fact_importance fi
-                ON af.fact_id = fi.fact_id AND fi.profile_id = ?
-            WHERE af.profile_id = ? AND af.confidence >= ?
-            ORDER BY af.created_at DESC
-            LIMIT ?
-        """, (profile, profile, min_importance / 10.0, max_nodes))
-        nodes = cursor.fetchall()
-
-        node_ids = {n['id'] for n in nodes}
-
-        # Fetch edges between these nodes
-        if node_ids:
-            ph = ','.join('?' * len(node_ids))
-            id_list = list(node_ids)
-            cursor.execute(f"""
-                SELECT source_id as source, target_id as target,
-                       weight, edge_type as relationship_type
-                FROM graph_edges
-                WHERE profile_id = ?
-                  AND source_id IN ({ph}) AND target_id IN ({ph})
-                ORDER BY weight DESC
-            """, [profile] + id_list + id_list)
-            all_links = cursor.fetchall()
-        else:
-            all_links = []
-
-        links = all_links
-        for n in nodes:
-            n['entities'] = []
-            n['content_preview'] = _preview(n.get('content'))
-            # v3.4.1: Default graph metrics when fact_importance has no data
-            if n.get('pagerank_score') is None:
-                n['pagerank_score'] = 0.0
-            if n.get('community_id') is None:
-                n['community_id'] = 0
-            if n.get('degree_centrality') is None:
-                n['degree_centrality'] = 0.0
-
-        # Filter edges to only those between displayed nodes
-        node_ids = {n['id'] for n in nodes}
-        links = [lk for lk in all_links
-                 if lk['source'] in node_ids and lk['target'] in node_ids]
-
-        # Compute clusters from memory_scenes
-        clusters = []
-        try:
-            cursor.execute("""
-                SELECT scene_id, theme, fact_ids_json
-                FROM memory_scenes WHERE profile_id = ?
-            """, (profile,))
-            for row in cursor.fetchall():
-                fact_ids = []
-                try:
-                    fact_ids = json.loads(row.get('fact_ids_json', '[]') or '[]')
-                except (json.JSONDecodeError, TypeError):
-                    pass
-                # Only include clusters that overlap with displayed nodes
-                overlap = [fid for fid in fact_ids if fid in node_ids]
-                if overlap:
-                    clusters.append({
-                        'cluster_id': row['scene_id'],
-                        'size': len(fact_ids),
-                        'visible_size': len(overlap),
-                        'theme': row.get('theme', ''),
-                    })
-        except Exception:
-            pass
-
-        return nodes, links, clusters
-
-    # V2 fallback
-    try:
-        cursor.execute("""
-            SELECT m.id, m.content, m.summary, m.category, m.cluster_id,
-                   m.importance, m.project_name, m.created_at, m.tags, gn.entities
-            FROM memories m LEFT JOIN graph_nodes gn ON m.id = gn.memory_id
-            WHERE m.importance >= ? AND m.profile = ?
-            ORDER BY m.importance DESC, m.updated_at DESC LIMIT ?
-        """, (min_importance, profile, max_nodes))
-    except Exception:
-        cursor.execute("""
-            SELECT id, content, summary, category, cluster_id, importance,
-                   project_name, created_at, tags, NULL as entities
-            FROM memories WHERE importance >= ? AND profile = ?
-            ORDER BY importance DESC, updated_at DESC LIMIT ?
-        """, (min_importance, profile, max_nodes))
-    nodes = cursor.fetchall()
-    for n in nodes:
-        ent = n.get('entities')
-        n['entities'] = json.loads(ent) if ent else []
-        n['content_preview'] = _preview(n.get('content'))
-    ids = [n['id'] for n in nodes]
-    links = _fetch_edges_v2(cursor, ids)
-    try:
-        cursor.execute("""
-            SELECT cluster_id, COUNT(*) as size, AVG(importance) as avg_importance
-            FROM memories WHERE cluster_id IS NOT NULL AND profile = ?
-            GROUP BY cluster_id
-        """, (profile,))
-        clusters = cursor.fetchall()
-    except Exception:
-        clusters = []
-    return nodes, links, clusters
-
-
-def _fetch_edges_v3(cursor, profile: str, fact_ids: list) -> list:
-    if not fact_ids:
-        return []
-    ph = ','.join('?' * len(fact_ids))
-    try:
-        cursor.execute(f"""
-            SELECT source_id as source, target_id as target,
-                   weight, edge_type as relationship_type
-            FROM graph_edges WHERE profile_id = ?
-              AND source_id IN ({ph}) AND target_id IN ({ph})
-            ORDER BY weight DESC
-        """, [profile] + fact_ids + fact_ids)
-        return cursor.fetchall()
-    except Exception:
-        return []
-
-
-def _fetch_edges_v2(cursor, memory_ids: list) -> list:
-    if not memory_ids:
-        return []
-    ph = ','.join('?' * len(memory_ids))
-    try:
-        cursor.execute(f"""
-            SELECT source_memory_id as source, target_memory_id as target,
-                   weight, relationship_type, shared_entities
-            FROM graph_edges
-            WHERE source_memory_id IN ({ph}) AND target_memory_id IN ({ph})
-            ORDER BY weight DESC
-        """, memory_ids + memory_ids)
-        links = cursor.fetchall()
-        for lk in links:
-            se = lk.get('shared_entities')
-            if se:
-                try:
-                    lk['shared_entities'] = json.loads(se)
-                except Exception:
-                    lk['shared_entities'] = []
-        return links
-    except Exception:
-        return []
-
-
-@router.get("/api/memories")
-async def get_memories(
-    request: Request,
-    category: Optional[str] = None,
-    project_name: Optional[str] = None,
-    cluster_id: Optional[int] = None,
-    min_importance: Optional[int] = None,
-    tags: Optional[str] = None,
-    limit: int = Query(BROWSE_PAGE_SIZE, ge=1, le=200),
-    offset: int = Query(0, ge=0),
-    filter: Optional[str] = Query(
-        None,
-        description="Named filter: 'high_reward' | 'being_forgotten'",
-    ),
-    scope: Optional[str] = Query(
-        None,
-        description=(
-            "Scope view (v3 only): 'shared' (shared with this profile), "
-            "'global' (global memories), 'all' (this profile + global + shared). "
-            "Default None = this profile only (unchanged isolation)."
-        ),
-    ),
-):
-    """List memories with optional filtering and pagination.
-
-    S9-DASH-07: ``filter`` enables dashboard "learning-visible" views:
-
-    * ``high_reward``: facts cited by ``action_outcomes`` with
-      ``reward >= 0.7`` in the last 30 days. Surfaces what the ranker
-      is actually learning from.
-    * ``being_forgotten``: facts in ``archive_status='archived'`` OR
-      with ``lifecycle='cold'`` AND no positive reward in 60 days.
-      Makes "memory decay" tangible to the operator.
-    """
-    try:
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        active_profile = get_active_profile()
-
-        use_v3 = _has_table(cursor, 'atomic_facts')
-
-        if use_v3:
-            # Scope view clause. Default (scope=None) is this-profile-only —
-            # identical isolation to before. Other values widen the view to
-            # global and/or shared-with-this-profile memories.
-            _esc = active_profile.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
-            _shared_pat = f'%"{_esc}"%'
-            if scope == "global":
-                scope_where = "scope = 'global'"
-                scope_params = []
-            elif scope == "shared":
-                scope_where = "scope = 'shared' AND shared_with LIKE ? ESCAPE '\\'"
-                scope_params = [_shared_pat]
-            elif scope == "all":
-                scope_where = (
-                    "(profile_id = ? OR scope = 'global' "
-                    "OR (scope = 'shared' AND shared_with LIKE ? ESCAPE '\\'))"
-                )
-                scope_params = [active_profile, _shared_pat]
-            else:
-                scope_where = "profile_id = ?"
-                scope_params = [active_profile]
-
-            # Withheld rows are excluded from BOTH the page and the total. On
-            # the author's store this list served 24 model-authored summaries
-            # in its first 50 rows and reported 5,218 memories against 3,919
-            # real ones -- the count a user reads, inflated by exactly the
-            # 1,299 rows 4.0.10 withheld.
-            visible = visible_fact_clause_for_connection(conn)
-            query = (
-                "SELECT fact_id as id, memory_id, content, fact_type as category, "
-                "confidence as importance, access_count, "
-                "created_at, created_at as updated_at, "
-                "session_id as project_name, scope, shared_with "
-                f"FROM atomic_facts WHERE {scope_where}{visible}"
-            )
-            params = list(scope_params)
-            count_base = (
-                "SELECT COUNT(*) as total FROM atomic_facts "
-                f"WHERE {scope_where}{visible}"
-            )
-        else:
-            query = """
-                SELECT id, content, summary, category, project_name, project_path,
-                       importance, cluster_id, depth, access_count, parent_id,
-                       created_at, updated_at, last_accessed, tags, memory_type
-                FROM memories WHERE profile = ?
-            """
-            params = [active_profile]
-            count_base = "SELECT COUNT(*) as total FROM memories WHERE profile = ?"
-
-        # count params must mirror the base WHERE params (scope-aware for v3).
-        count_params = list(params)
-
-        if category:
-            if use_v3:
-                query += " AND fact_type = ?"
-            else:
-                query += " AND category = ?"
-            params.append(category)
-            count_base += " AND category = ?" if not use_v3 else " AND fact_type = ?"
-            count_params.append(category)
-        if project_name:
-            if use_v3:
-                query += " AND session_id = ?"
-            else:
-                query += " AND project_name = ?"
-            params.append(project_name)
-            count_base += " AND project_name = ?" if not use_v3 else " AND session_id = ?"
-            count_params.append(project_name)
-        if cluster_id is not None and not use_v3:
-            query += " AND cluster_id = ?"
-            params.append(cluster_id)
-            count_base += " AND cluster_id = ?"
-            count_params.append(cluster_id)
-        if min_importance:
-            if use_v3:
-                query += " AND confidence >= ?"
-                params.append(min_importance / 10.0)
-            else:
-                query += " AND importance >= ?"
-                params.append(min_importance)
-        if tags and not use_v3:
-            tag_list = [t.strip() for t in tags.split(',')]
-            for tag in tag_list:
-                query += " AND tags LIKE ?"
-                params.append(f'%{tag}%')
-
-        # S9-DASH-07: named filters — "high_reward" and "being_forgotten".
-        # Only supported on the v3 (atomic_facts) path — v2 fallback
-        # ignores the flag silently.
-        if filter and use_v3:
-            if filter == "high_reward":
-                query += (
-                    " AND fact_id IN ("
-                    "  SELECT DISTINCT json_each.value"
-                    "  FROM action_outcomes, json_each(action_outcomes.fact_ids_json)"
-                    "  WHERE action_outcomes.reward >= 0.7"
-                    "    AND datetime(action_outcomes.settled_at) >= "
-                    "        datetime('now', '-30 day')"
-                    ")"
-                )
-                count_base += (
-                    " AND fact_id IN ("
-                    "  SELECT DISTINCT json_each.value"
-                    "  FROM action_outcomes, json_each(action_outcomes.fact_ids_json)"
-                    "  WHERE action_outcomes.reward >= 0.7"
-                    "    AND datetime(action_outcomes.settled_at) >= "
-                    "        datetime('now', '-30 day')"
-                    ")"
-                )
-            elif filter == "being_forgotten":
-                # Cold / archived + no recent positive reward.
-                query += (
-                    " AND ("
-                    "  archive_status = 'archived' OR "
-                    "  (lifecycle = 'cold' AND fact_id NOT IN ("
-                    "    SELECT DISTINCT json_each.value"
-                    "    FROM action_outcomes, json_each(action_outcomes.fact_ids_json)"
-                    "    WHERE action_outcomes.reward >= 0.5"
-                    "      AND datetime(action_outcomes.settled_at) >= "
-                    "          datetime('now', '-60 day')"
-                    "  ))"
-                    ")"
-                )
-                count_base += (
-                    " AND ("
-                    "  archive_status = 'archived' OR "
-                    "  (lifecycle = 'cold' AND fact_id NOT IN ("
-                    "    SELECT DISTINCT json_each.value"
-                    "    FROM action_outcomes, json_each(action_outcomes.fact_ids_json)"
-                    "    WHERE action_outcomes.reward >= 0.5"
-                    "      AND datetime(action_outcomes.settled_at) >= "
-                    "          datetime('now', '-60 day')"
-                    "  ))"
-                    ")"
-                )
-
-        query += " ORDER BY created_at DESC LIMIT ? OFFSET ?"
-        params.extend([limit, offset])
-
-        cursor.execute(query, params)
-        memories = cursor.fetchall()
-
-        cursor.execute(count_base, count_params)
-        total = cursor.fetchone()['total']
-
-        conn.close()
-
-        return {
-            "memories": memories, "total": total,
-            "limit": limit, "offset": offset,
-            "has_more": (offset + limit) < total,
-        }
-
-    except Exception:
-        raise _internal_error("Database error")
-
-
-@router.get("/api/graph")
-async def get_graph(
-    request: Request,
-    max_nodes: int = Query(100, ge=10, le=10000),
-    min_importance: int = Query(1, ge=1, le=10),
-):
-    """Get knowledge graph data for D3.js force-directed visualization."""
-    try:
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        active_profile = get_active_profile()
-
-        use_v3 = _has_table(cursor, 'atomic_facts')
-
-        nodes, links, clusters = _fetch_graph_data(
-            cursor, active_profile, use_v3, min_importance, max_nodes,
-        )
-
-        conn.close()
-
-        return {
-            "nodes": nodes, "links": links, "clusters": clusters,
-            "metadata": {
-                "node_count": len(nodes), "edge_count": len(links),
-                "cluster_count": len(clusters) if clusters else 0,
-                "filters_applied": {"max_nodes": max_nodes, "min_importance": min_importance},
-            },
-        }
-
-    except Exception:
-        raise _internal_error("Graph error")
-
-
-@router.post("/api/search")
-async def search_memories(request: Request, body: SearchRequest):
-    """Semantic search using the daemon's in-process engine.
-
-    v3.4.61: Replaced WorkerPool.shared() (subprocess-based, cold-starts on
-    every request, always >15s) with the daemon's own engine that is already
-    loaded and warm. WorkerPool.shared() was legacy from v3.4.32 before the
-    unified daemon architecture. Using the daemon engine matches what the /recall
-    HTTP endpoint does and shares its warm SQLite page cache, bringing dashboard
-    search from >15s timeout to <1s warm.
-
-    Falls back to direct DB LIKE search if engine is unavailable.
-    """
-    from superlocalmemory.core.recall_gate import begin_recall, end_recall
-    begin_recall()
-    try:
-        # Use the daemon engine directly — already loaded, shares warm cache.
-        # v3.4.63: engine.recall() is synchronous/blocking (~2-10s). Calling it
-        # directly in an async route blocks the ASGI event loop — Chrome detects
-        # a stalled connection and aborts with "signal is aborted without reason"
-        # before the response arrives. Fix: run in a thread-pool executor so the
-        # event loop stays alive to send keepalive frames.
-        # v3.8.2: fast=True — the dashboard search BOX is a snappy retrieval
-        # list (all six local channels + reranker), never the internal agentic
-        # LLM round, which would reintroduce the multi-second hang this endpoint
-        # is regression-tested against (test_search_fast_param_and_profile_isolation).
-        # The human-facing LLM synthesis lives on separate paths that are NOT the
-        # search list: the "ask" memory-chat (/api/v3/chat/stream, Ollama Mode B)
-        # and the precomputed knowledge-cluster summaries (core.community_summary,
-        # Mode B/C). So search stays fast; synthesis is where the LLM adds value.
-        import asyncio
-        import time as _time
-        engine = _get_engine(request)
-        if engine is not None:
-            loop = asyncio.get_running_loop()
-            t0 = _time.monotonic()
-            # T-window: prefer an explicit ``window`` spec; otherwise derive a
-            # range from the legacy date_from/date_to pair when both are set.
-            _window = getattr(body, "window", None) or ""
-            if not _window and getattr(body, "date_from", None) and getattr(body, "date_to", None):
-                _window = f"{body.date_from}..{body.date_to}"
-            # v3.8.3: bound the synchronous recall. Under a concurrent
-            # maintenance pass or a busy embedder it can run tens of seconds
-            # and the browser aborts the fetch. If it exceeds the budget we
-            # fall through to the fast keyword search below, so the dashboard
-            # ALWAYS returns instead of failing with an abort.
-            _recall_future = loop.run_in_executor(
-                None,
-                lambda: engine.recall(
-                    body.query, limit=body.limit, fast=True,
-                    window=_window or None,
-                    # Name the surface. A recall with no name leaves no record
-                    # an outcome can be matched to, and a search typed into the
-                    # dashboard is one continuous thread of use, not a
-                    # conversation turn.
-                    session_id=f"dashboard:{get_active_profile()}",
-                ),
-            )
-            # A run_in_executor thread cannot be cancelled, and wait_for() on it
-            # blocks until the thread finishes (defeating the timeout). So poll
-            # the future without blocking the event loop and give up at the
-            # deadline — the orphaned recall completes in the background and its
-            # result is discarded. This is what bounds dashboard-search latency.
-            _budget = _search_recall_timeout_s()
-            _deadline = loop.time() + _budget
-            while not _recall_future.done() and loop.time() < _deadline:
-                await asyncio.sleep(0.05)
-            if _recall_future.done():
-                response = _recall_future.result()
-            else:
-                # Ensure the orphaned future's eventual result/exception is
-                # retrieved so asyncio doesn't log "never retrieved".
-                _recall_future.add_done_callback(
-                    lambda f: (f.cancelled() or f.exception())
-                )
-                logger.warning(
-                    "search_memories: semantic recall exceeded %.0fs budget for "
-                    "%r — serving keyword fallback",
-                    _budget, (body.query or "")[:80],
-                )
-                response = None
-            if response is not None:
-                elapsed_ms = round((_time.monotonic() - t0) * 1000, 1)
-                from superlocalmemory.server.recall_serializer import (
-                    recall_response_metadata,
-                    serialize_recall_response,
-                )
-                results, no_confident_match = serialize_recall_response(
-                    response,
-                    limit=body.limit,
-                    per_fact_max=300,
-                    total_max=max(300, body.limit * 300),
-                )
-                return {
-                    "query": body.query,
-                    "results": results,
-                    "total": len(results),
-                    "query_type": getattr(response, "query_type", "semantic"),
-                    "retrieval_time_ms": elapsed_ms,
-                    "no_confident_match": no_confident_match,
-                    **recall_response_metadata(response),
-                }
-            # recall timed out — fall through to the fast keyword search.
-
-        # Fallback: direct DB text search (engine not ready OR recall over budget)
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        active_profile = get_active_profile()
-        cursor.execute("""
-            SELECT fact_id, content, confidence as memory_confidence,
-                   fact_type as category, created_at
-            FROM atomic_facts
-            WHERE profile_id = ? AND content LIKE ?
-            ORDER BY confidence DESC LIMIT ?
-        """, (active_profile, f'%{body.query}%', body.limit))
-        rows = cursor.fetchall()
-        conn.close()
-
-        results = [{
-            **row,
-            "score": None,
-            "relevance_score": None,
-            "ranking_score": None,
-            "confidence": row.get("memory_confidence"),
-            "rank_position": position,
-        } for position, row in enumerate(rows, start=1)]
-
-        return {
-            "query": body.query, "results": results, "total": len(results),
-            "query_type": "text_search", "retrieval_time_ms": 0,
-            "retrieval_mode": "degraded_lexical",
-            "score_contract_version": "2",
-            "calibration_status": "uncalibrated",
-            "calibration_id": None,
-            "answer_confidence": None,
-            "abstained": not bool(results),
-            "abstention_reason": None if results else "no_candidates",
-            "no_confident_match": False,
-        }
-
-    except Exception:
-        raise _internal_error("Search error")
-    finally:
-        end_recall()
-
-
-@router.get("/api/summary")
-async def get_summary(request: Request, kind: str = "day", target: str = ""):
-    """Readable summary of memories: a day, a project, or one session (#113).
-
-    The dashboard surface for the summary layer. 4.0.6 shipped the generators
-    with no caller, 4.0.7 added the CLI, 4.0.8 adds this and the MCP tool — the
-    "no command, tool or endpoint" gap, closed at the third point.
-
-    Always returns ``coverage`` and ``source_fact_ids``: a summary that hides how
-    much it covered is the opaque generic summary issue #113 warned against.
-    Reads memory.db directly; never runs during remember or recall.
-    """
-    from datetime import date as _date, timedelta as _timedelta
-
-    kind = (kind or "day").strip().lower()
-    if kind not in ("day", "project", "session"):
-        raise HTTPException(status_code=400, detail=f"unknown summary kind '{kind}'")
-
-    profile = get_active_profile()
-    from superlocalmemory.infra.data_root import state_path
-    db_path = state_path("memory.db")
-    if not db_path.exists():
-        raise HTTPException(status_code=404, detail="no memory database")
-
-    # Pass the loaded config so Mode B/C write the summary. Omitting it silently
-    # forces the extractive path for every caller regardless of mode.
-    try:
-        from superlocalmemory.core.config import SLMConfig
-        cfg = SLMConfig.load()
-    except Exception:
-        cfg = None
-
-    try:
-        if kind == "day":
-            from superlocalmemory.summaries import generate_daily_reflection
-            day = (target or "").strip() or _date.today().isoformat()
-            if day == "today":
-                day = _date.today().isoformat()
-            elif day == "yesterday":
-                day = (_date.today() - _timedelta(days=1)).isoformat()
-            result = generate_daily_reflection(db_path, day, profile, cfg)
-        elif kind == "project":
-            if not (target or "").strip():
-                raise HTTPException(status_code=400, detail="project requires target")
-            from superlocalmemory.summaries import generate_project_work_log
-            result = generate_project_work_log(db_path, target.strip(), profile, cfg)
-        else:
-            if not (target or "").strip():
-                raise HTTPException(status_code=400, detail="session requires target")
-            from superlocalmemory.summaries import generate_session_summary
-            result = generate_session_summary(db_path, target.strip(), profile, cfg)
-    except HTTPException:
-        raise
-    except Exception:
-        raise _internal_error("Summary generation error")
-
-    # Say why, not just what. The response already reported that a summary was
-    # assembled rather than written; someone seeing a plainer result than they
-    # expected still had no way to learn that a written one needs a model, and
-    # would reasonably read the feature as broken.
-    from superlocalmemory.core.mode_capability import llm_capability
-
-    generated = str(getattr(result, "generated_by", "") or "")
-    return {
-        "kind": result.kind,
-        "profile_id": result.profile_id,
-        "summary": result.content,
-        "coverage": result.coverage,
-        "generated_by": result.generated_by,
-        "source_fact_ids": result.source_fact_ids,
-        "source_count": len(result.source_fact_ids),
-        "metadata": result.metadata,
-        "capability": llm_capability(
-            cfg,
-            # This call has just been made, so its outcome is the honest answer
-            # about availability -- better than asking the configuration again.
-            llm_reachable=generated.startswith("llm"),
-        ),
-    }
-
-
-@router.get("/api/summary/projects")
-async def get_summary_projects(request: Request):
-    """Projects SuperLocalMemory has actually observed, for the summary picker.
-
-    WHY THIS EXISTS
-    ---------------
-    SLM is installed globally and the dashboard is a browser tab — it has no
-    working directory, so there is no such thing as "this project" from the
-    server's point of view. 4.0.8 shipped a "This project" button that sent an
-    empty target and produced "project requires target" every time. A button
-    that cannot know its own answer is the wrong control; a list of the projects
-    we have seen is the right one.
-
-    Scope comes from ``tool_events.project_path`` — the directory an agent was
-    working in when it called SLM. Deliberately NOT ``entity_profiles.
-    project_name``, which has exactly one distinct value on a real store (see
-    the note at the top of summaries/project_work_log.py).
-
-    ``tool_events`` is a bounded ring buffer, so this lists recently active
-    projects rather than every project in history. ``truncated`` says so
-    honestly instead of implying the list is exhaustive.
-    """
-    profile = get_active_profile()
-    try:
-        conn = get_db_connection()
-        # get_db_connection() hands back a SHARED read connection, and other
-        # handlers set row_factory on it. Never index these rows positionally —
-        # whichever handler ran last decides whether r[0] is a column or a
-        # KeyError. Name the columns and read them by name.
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        cursor.execute(
-            """
-            SELECT project_path AS path, COUNT(*) AS events
-              FROM tool_events
-             WHERE project_path IS NOT NULL AND project_path != ''
-               AND profile_id = ?
-             GROUP BY project_path
-             ORDER BY events DESC
-             LIMIT 50
-            """,
-            (profile,),
-        )
-        rows = cursor.fetchall()
-        total = cursor.execute(
-            "SELECT COUNT(*) AS n FROM tool_events"
-        ).fetchone()["n"]
-    except Exception:
-        raise _internal_error("Project list error")
-
-    projects = [
-        {
-            "path": r["path"],
-            "events": r["events"],
-            "label": _project_label(r["path"]),
-        }
-        for r in rows
-    ]
-    return {
-        "projects": projects,
-        "profile_id": profile,
-        # Surfaced so the UI can explain an unexpectedly short list rather than
-        # leaving the user to assume their project was never recorded.
-        "truncated": total >= _TOOL_EVENT_RING_SIZE,
-        "event_rows": total,
-    }
-
-
-#: tool_events is capped; at the cap the project list is a recent window, not history.
-_TOOL_EVENT_RING_SIZE = 2000
-
-
-def _project_label(path: str) -> str:
-    """Short, human label for a project path.
-
-    Full paths are long and share prefixes ("/Users/x/Documents/official/..."),
-    so a dropdown of raw paths is unreadable. Last two segments keep sibling
-    projects distinguishable without the noise.
-    """
-    parts = [p for p in str(path).replace("\\", "/").split("/") if p]
-    if not parts:
-        return str(path)
-    return "/".join(parts[-2:]) if len(parts) > 1 else parts[-1]
-
-
-@router.get("/api/clusters")
-async def get_clusters(request: Request):
-    """Get cluster information with member counts and statistics."""
-    try:
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        profile = get_active_profile()
-        unclustered = 0
-
-        # V3 schema: memory_scenes stores fact_ids_json (JSON array)
-        if _has_table(cursor, 'memory_scenes'):
-            cursor.execute("""
-                SELECT scene_id as cluster_id, theme, fact_ids_json,
-                       entity_ids_json, created_at as first_memory
-                FROM memory_scenes WHERE profile_id = ?
-                ORDER BY created_at DESC
-            """, (profile,))
-            raw_scenes = cursor.fetchall()
-            clusters = []
-            for scene in raw_scenes:
-                fact_ids = []
-                try:
-                    fact_ids = json.loads(scene.get('fact_ids_json', '[]') or '[]')
-                except (json.JSONDecodeError, TypeError):
-                    pass
-                entity_ids = []
-                try:
-                    entity_ids = json.loads(scene.get('entity_ids_json', '[]') or '[]')
-                except (json.JSONDecodeError, TypeError):
-                    pass
-                clusters.append({
-                    'cluster_id': scene['cluster_id'],
-                    'member_count': len(fact_ids),
-                    'categories': scene.get('theme', ''),
-                    'summary': scene.get('theme', ''),
-                    'first_memory': scene.get('first_memory', ''),
-                    'top_entities': entity_ids[:5],
-                })
-            # Filter out empty clusters
-            clusters = [c for c in clusters if c['member_count'] > 0]
-            clusters.sort(key=lambda c: c['member_count'], reverse=True)
-
-            # Count facts not in any scene
-            all_scene_fact_ids = set()
-            for scene in raw_scenes:
-                try:
-                    ids = json.loads(scene.get('fact_ids_json', '[]') or '[]')
-                    all_scene_fact_ids.update(ids)
-                except (json.JSONDecodeError, TypeError):
-                    pass
-            total_facts = cursor.execute(
-                "SELECT COUNT(*) as c FROM atomic_facts WHERE profile_id = ?",
-                (profile,),
-            ).fetchone()['c']
-            unclustered = total_facts - len(all_scene_fact_ids)
-        else:
-            # V2 fallback
-            try:
-                cursor.execute("""
-                    SELECT cluster_id, COUNT(*) as member_count,
-                           AVG(importance) as avg_importance,
-                           GROUP_CONCAT(DISTINCT category) as categories
-                    FROM memories WHERE cluster_id IS NOT NULL AND profile = ?
-                    GROUP BY cluster_id ORDER BY member_count DESC
-                """, (profile,))
-                clusters = [dict(r, top_entities=[]) for r in cursor.fetchall()]
-            except Exception:
-                clusters = []
-            try:
-                cursor.execute(
-                    "SELECT COUNT(*) as c FROM memories WHERE cluster_id IS NULL AND profile = ?",
-                    (profile,),
-                )
-                unclustered = cursor.fetchone()['c']
-            except Exception:
-                unclustered = 0
-
-        conn.close()
-        return {
-            "clusters": clusters,
-            "total_clusters": len(clusters),
-            "unclustered_count": unclustered,
-        }
-    except Exception:
-        raise _internal_error("Cluster error")
-
-
-@router.get("/api/clusters/{cluster_id}")
-async def get_cluster_detail(
-    request: Request,
-    cluster_id: str,
-    limit: int = Query(BROWSE_PAGE_SIZE, ge=1, le=200),
-):
-    """Get detailed view of a specific cluster (scene)."""
-    try:
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        profile = get_active_profile()
-
-        if _has_table(cursor, 'memory_scenes'):
-            # Get fact IDs from the scene's JSON array
-            cursor.execute(
-                "SELECT fact_ids_json, theme FROM memory_scenes "
-                "WHERE scene_id = ? AND profile_id = ?",
-                (cluster_id, profile),
-            )
-            scene_row = cursor.fetchone()
-            if scene_row:
-                fact_ids = []
-                try:
-                    fact_ids = json.loads(scene_row.get('fact_ids_json', '[]') or '[]')
-                except (json.JSONDecodeError, TypeError):
-                    pass
-                if fact_ids:
-                    ph = ','.join('?' * min(len(fact_ids), limit))
-                    cursor.execute(f"""
-                        SELECT fact_id as id, content, fact_type as category,
-                               confidence as importance, created_at
-                        FROM atomic_facts
-                        WHERE profile_id = ? AND fact_id IN ({ph})
-                        ORDER BY confidence DESC
-                    """, [profile] + fact_ids[:limit])
-                else:
-                    cursor.execute("SELECT 1 WHERE 0")  # empty result
-            else:
-                cursor.execute("SELECT 1 WHERE 0")  # empty result
-        else:
-            cursor.execute("""
-                SELECT id, content, summary, category, project_name, importance, created_at, tags
-                FROM memories WHERE cluster_id = ? AND profile = ?
-                ORDER BY importance DESC, created_at DESC LIMIT ?
-            """, (cluster_id, profile, limit))
-        members = cursor.fetchall()
-        conn.close()
-        if not members:
-            raise HTTPException(status_code=404, detail="Cluster not found")
-        # Generate cluster summary
-        # v3.7.8: previously routed through WorkerPool.shared(), a subprocess
-        # cache never recycled on a profile switch (CRITICAL cross-profile
-        # leak — up to 120s stale). Use the daemon's own resident,
-        # lease-protected engine's config instead; the summarizer only
-        # consumes already profile-filtered `texts` above, so this closes
-        # the stale-engine window without changing behavior.
-        summary = ""
-        try:
-            texts = [m.get("content", "")[:200] for m in members[:10] if m.get("content")]
-            if texts:
-                from superlocalmemory.core.summarizer import Summarizer
-                from superlocalmemory.server.routes.helpers import get_engine_lazy
-
-                # v3.4.64: Do NOT call runtime.operation() synchronously in an
-                # async route — if a transition is pending, acquire_operation()
-                # blocks the event loop thread, deadlocking the drain.  The
-                # middleware already holds an operation lease for this request;
-                # the engine is stable for the full duration of the handler.
-                engine = get_engine_lazy(request.app.state)
-                if engine is not None:
-                    summarizer = Summarizer(engine._config)
-                    summary = summarizer.summarize_cluster(
-                        [{"content": t} for t in texts]
-                    ) or ""
-        except Exception:
-            pass
-
-        return {
-            "cluster_info": {"cluster_id": cluster_id, "total_members": len(members)},
-            "summary": summary,
-            "members": members,
-            "connections": [],
-        }
-    except HTTPException:
-        raise
-    except Exception:
-        raise _internal_error("Cluster detail error")
-
-
-@router.get("/api/memories/{memory_id}/facts")
-async def get_memory_facts(request: Request, memory_id: str):
-    """Get original memory text with all its child atomic facts.
-
-    v3.7.8: previously routed through WorkerPool.shared(), a subprocess
-    engine cached at process init and never recycled on a profile switch
-    (CRITICAL cross-profile leak — served the OLD profile's facts for up to
-    120s after a switch). Uses the daemon's own resident, lease-protected
-    engine instead, exactly like the /recall route.
-    """
-    try:
-        from superlocalmemory.server.routes.helpers import get_engine_lazy
-
-        # v3.4.64: Do NOT call runtime.operation() synchronously in an async
-        # route — blocks the event loop when a transition is pending.  The
-        # middleware already holds an operation lease; the engine and its
-        # profile_id are stable for the full duration of this request.
-        engine = get_engine_lazy(request.app.state)
-        if engine is None:
-            raise HTTPException(status_code=503, detail="Engine not initialized")
-        active_profile = engine.profile_id
-        mem_map = engine._db.get_memory_content_batch(
-            [memory_id], active_profile, include_global=True, include_shared=True,
-        )
-        original = mem_map.get(memory_id, "")
-        facts = engine._db.get_facts_by_memory_id(memory_id, active_profile)
-        fact_list = [
-            {
-                "fact_id": f.fact_id,
-                "content": f.content,
-                "fact_type": (
-                    f.fact_type.value if hasattr(f.fact_type, "value")
-                    else str(f.fact_type)
-                ),
-                "confidence": round(f.confidence, 3),
-                "created_at": f.created_at,
-            }
-            for f in facts
-        ]
-        return {
-            "ok": True,
-            "memory_id": memory_id,
-            "original_content": original,
-            "facts": fact_list,
-            "fact_count": len(fact_list),
-        }
-    except HTTPException:
-        raise
-    except Exception:
-        raise _internal_error()
-
-
-@router.get("/api/memories/{memory_id}/detail")
-async def get_memory_detail(request: Request, memory_id: str):
-    """Full memory row + all child atomic facts (for dashboard modal)."""
-    try:
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        active_profile = get_active_profile()
-
-        cursor.execute(
-            "SELECT memory_id, content, session_id, speaker, role, "
-            "session_date, created_at, metadata_json "
-            "FROM memories WHERE memory_id = ? AND profile_id = ?",
-            (memory_id, active_profile),
-        )
-        mem = cursor.fetchone()
-        if not mem:
-            conn.close()
-            raise HTTPException(status_code=404, detail="Memory not found")
-
-        cursor.execute(
-            "SELECT fact_id, content, fact_type, confidence, importance, "
-            "access_count, created_at, entities_json "
-            "FROM atomic_facts WHERE memory_id = ? AND profile_id = ? "
-            "ORDER BY created_at ASC",
-            (memory_id, active_profile),
-        )
-        facts = cursor.fetchall()
-        conn.close()
-
-        try:
-            mem["metadata"] = json.loads(mem.pop("metadata_json") or "{}")
-        except Exception:
-            mem["metadata"] = {}
-        for f in facts:
-            try:
-                f["entities"] = json.loads(f.pop("entities_json") or "[]")
-            except Exception:
-                f["entities"] = []
-
-        return {
-            "memory": mem,
-            "facts": facts,
-            "fact_count": len(facts),
-        }
-    except HTTPException:
-        raise
-    except Exception:
-        raise _internal_error("Detail error")
-
-
-@router.get("/api/facts/{fact_id}")
-async def get_fact_detail(request: Request, fact_id: str):
-    """Single atomic fact detail (for fact popup)."""
-    try:
-        conn = get_db_connection()
-        conn.row_factory = dict_factory
-        cursor = conn.cursor()
-        active_profile = get_active_profile()
-
-        cursor.execute(
-            "SELECT f.fact_id, f.memory_id, f.content, f.fact_type, "
-            "f.confidence, f.importance, f.access_count, f.created_at, "
-            "f.entities_json, f.canonical_entities_json, f.session_id, "
-            "m.content AS source_memory_content "
-            "FROM atomic_facts f "
-            "LEFT JOIN memories m ON f.memory_id = m.memory_id "
-            "WHERE f.fact_id = ? AND f.profile_id = ?",
-            (fact_id, active_profile),
-        )
-        row = cursor.fetchone()
-        conn.close()
-        if not row:
-            raise HTTPException(status_code=404, detail="Fact not found")
-        try:
-            row["entities"] = json.loads(row.pop("entities_json") or "[]")
-        except Exception:
-            row["entities"] = []
-        try:
-            row["canonical_entities"] = json.loads(
-                row.pop("canonical_entities_json") or "[]"
-            )
-        except Exception:
-            row["canonical_entities"] = []
-        row["code_links"] = _code_links_for_fact(fact_id)
-        return row
-    except HTTPException:
-        raise
-    except Exception:
-        raise _internal_error("Fact detail error")
-
-
-def _code_links_for_fact(fact_id: str) -> list[dict]:
-    """Code entities this fact mentions, from the code graph.
-
-    Fail-open by design: this is a display extra on a detail popup. No code graph
-    built, bridge switched off, or database missing all mean "no section shown",
-    never an error on the fact itself. A user who has never touched the code
-    graph must not see a failure because of a feature they do not use.
-
-    Reads code_graph.db, which is a separate database from memory.db and is never
-    opened by the recall path — so nothing here can affect recall.
-    """
-    try:
-        from superlocalmemory.code_graph.config import CodeGraphConfig
-
-        cfg = CodeGraphConfig.load()
-        if not (cfg.enabled and cfg.bridge_enabled):
-            return []
-        db_path = cfg.get_db_path()
-        if not db_path.exists():
-            return []
-
-        import sqlite3
-
-        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
-        try:
-            conn.row_factory = dict_factory
-            rows = conn.execute(
-                "SELECT cml.link_type, cml.confidence, cml.is_stale, "
-                "       cml.enriched_description, "
-                "       gn.name, gn.qualified_name, gn.kind, gn.file_path "
-                "FROM code_memory_links cml "
-                "LEFT JOIN graph_nodes gn ON gn.node_id = cml.code_node_id "
-                "WHERE cml.slm_fact_id = ? "
-                "ORDER BY cml.confidence DESC, gn.qualified_name",
-                (fact_id,),
-            ).fetchall()
-        finally:
-            conn.close()
-
-        return [
-            {
-                "name": r.get("name") or "",
-                "qualified_name": r.get("qualified_name") or "",
-                "kind": r.get("kind") or "",
-                "file_path": r.get("file_path") or "",
-                "link_type": r.get("link_type") or "mentions",
-                "confidence": r.get("confidence"),
-                "is_stale": bool(r.get("is_stale")),
-                "description": r.get("enriched_description") or "",
-            }
-            for r in rows
-            # A link whose node is gone (LEFT JOIN produced no row) is a stale
-            # pointer, not something to render as a blank entry.
-            if r.get("qualified_name")
-        ]
-    except Exception:
-        logger.debug("code links unavailable for %s", fact_id, exc_info=True)
-        return []
-
-
-@router.delete("/api/memories/{fact_id}")
-async def delete_memory(request: Request, fact_id: str):
-    """Delete a specific memory (atomic fact) by ID."""
-    engine, _active_profile, hook_context = _authorize_memory_mutation(
-        request, "delete", fact_id, run_pre_hook=False,
-    )
-    try:
-        from superlocalmemory.core.mutations import delete_fact_authorized
-
-        result = delete_fact_authorized(
-            engine,
-            fact_id,
-            trusted_actor_id=hook_context["agent_id"],
-            source_agent_id="dashboard",
-            canonical_runtime=_mutation_runtime_or_missing_fact(
-                request, engine, _active_profile, fact_id,
-            ),
-            idempotency_key=_mutation_idempotency_key(request),
-        )
-        if not result.get("ok"):
-            if result.get("retryable"):
-                raise HTTPException(
-                    status_code=503,
-                    detail="Erasure incomplete (projection residue); retry shortly",
-                )
-            raise HTTPException(status_code=404, detail="Memory not found")
-        return {
-            "success": True,
-            "deleted": fact_id,
-            "erasure_verified": bool(result.get("erasure_verified", False)),
-            "erasure_state": result.get("erasure_state", "FAILED"),
-        }
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise _canonical_mutation_error(exc, "Delete error")
-
-
-@router.post("/api/memories/{fact_id}/forget")
-async def forget_memory(request: Request, fact_id: str):
-    """S9-DASH-08: soft-forget a fact — flip archive_status='archived'.
-
-    Non-destructive: the row stays in ``atomic_facts`` for audit and
-    can be un-archived later. Default recall paths filter it out.
-    The fact's payload is ALSO copied into ``memory_archive`` so a
-    future ``slm restore`` can bring it back.
-    """
-    engine, active_profile, hook_context = _authorize_memory_mutation(
-        request, "delete", fact_id,
-        run_pre_hook=False,
-    )
-    try:
-        engine._hooks.run_pre("delete", hook_context)
-        result = _canonical_mutation_runtime(request).archive_fact(
-            active_profile,
-            fact_id,
-            idempotency_key=_mutation_idempotency_key(request),
-        )
-        if not result.get("ok"):
-            raise HTTPException(status_code=404, detail="Memory not found")
-        engine._hooks.run_post("delete", hook_context)
-        return {"success": True, "fact_id": fact_id, "archived_at": result["archived_at"]}
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise _canonical_mutation_error(exc, "Forget error")
-
-
-@router.post("/api/memories/{fact_id}/merge")
-async def merge_memory(request: Request, fact_id: str):
-    """S9-DASH-08: merge this fact into another (keep the other).
-
-    Body: ``{into: <kept_fact_id>}``.
-
-    Writes a ``memory_merge_log`` row (M011) for provenance and marks
-    the loser's ``merged_into`` column. The loser is archived so it
-    no longer appears in default recall. The winner is untouched.
-    """
-    engine, active_profile, hook_context = _authorize_memory_mutation(
-        request, "delete", fact_id,
-        run_pre_hook=False,
-    )
-    try:
-        body = await request.json()
-        kept = str((body or {}).get("into", "")).strip()
-        if not kept:
-            raise HTTPException(400, "Body field 'into' is required")
-        # S9-AUDIT: cap length defensively — fact_ids are UUID-v4 36 chars.
-        if len(kept) > 200:
-            raise HTTPException(400, "'into' exceeds 200-char limit")
-        if kept == fact_id:
-            raise HTTPException(400, "Cannot merge a fact into itself")
-        engine._hooks.run_pre("delete", hook_context)
-        result = _canonical_mutation_runtime(request).merge_fact(
-            active_profile,
-            fact_id,
-            kept,
-            idempotency_key=_mutation_idempotency_key(request),
-        )
-        if not result.get("ok"):
-            raise HTTPException(404, "Both fact_ids must exist in the active profile")
-        engine._hooks.run_post("delete", hook_context)
-        return {
-            "success": True,
-            "merged": fact_id,
-            "into": kept,
-            "merged_at": result["merged_at"],
-        }
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise _canonical_mutation_error(exc, "Merge error")
-
-
-@router.patch("/api/memories/{fact_id}", status_code=202)
-async def edit_memory(request: Request, fact_id: str):
-    """Propose an immutable, review-required correction for one memory."""
-    try:
-        body = await request.json()
-        new_content = (body.get("content") or "").strip()
-        if not new_content:
-            raise HTTPException(status_code=400, detail="content is required")
-        engine, _active_profile, hook_context = _authorize_memory_mutation(
-            request,
-            "update",
-            fact_id,
-            content_preview=new_content,
-            run_pre_hook=False,
-        )
-        from superlocalmemory.core.mutations import update_fact_authorized
-
-        result = update_fact_authorized(
-            engine,
-            fact_id,
-            new_content,
-            trusted_actor_id=hook_context["agent_id"],
-            source_agent_id="dashboard",
-            canonical_runtime=_canonical_mutation_runtime(request),
-            idempotency_key=_mutation_idempotency_key(request),
-        )
-        if not result.get("ok"):
-            raise HTTPException(status_code=404, detail="Memory not found")
-        if result.get("unchanged"):
-            return {"success": True, "fact_id": fact_id, "content": new_content, "unchanged": True}
-        correction = result["correction_case"]
-        return {
-            "success": True,
-            "fact_id": fact_id,
-            "predecessor_fact_id": result["predecessor_fact_id"],
-            "successor_fact_id": result["successor_fact_id"],
-            "correction_case": correction,
-            "review_required": True,
-            "status": "proposed",
-        }
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise _canonical_mutation_error(exc, "Edit error")
-
-
-@router.post("/api/corrections/{case_id}/{action}")
-async def review_correction(request: Request, case_id: str, action: str):
-    """Apply, reject, or roll back an active-profile correction case.
-
-    The caller authenticates through the daemon boundary.  It cannot select a
-    profile, fact scope, or trust tier; the canonical writer rechecks all of
-    those fields in its one SQLite transaction.
-    """
-    try:
-        body = await request.json()
-        if action not in {"apply", "reject", "rollback"}:
-            raise HTTPException(422, detail="action must be apply, reject, or rollback")
-        expected_version = body.get("expected_version") if isinstance(body, dict) else None
-        if not isinstance(expected_version, int) or isinstance(expected_version, bool):
-            raise HTTPException(422, detail="expected_version must be a non-negative integer")
-        if expected_version < 0:
-            raise HTTPException(422, detail="expected_version must be a non-negative integer")
-        event_valid_until = body.get("event_valid_until") if isinstance(body, dict) else None
-        if event_valid_until is not None and not isinstance(event_valid_until, str):
-            raise HTTPException(422, detail="event_valid_until must be an RFC3339 timestamp")
-        if event_valid_until is not None and action != "apply":
-            raise HTTPException(422, detail="event_valid_until is permitted only for apply")
-        engine, active_profile, hook_context = _authorize_memory_mutation(
-            request, "update", case_id, run_pre_hook=False
-        )
-        result = _canonical_mutation_runtime(request).transition_correction(
-            active_profile,
-            case_id,
-            action=action,
-            expected_version=expected_version,
-            actor_id=hook_context["agent_id"],
-            event_valid_until=event_valid_until,
-            idempotency_key=_mutation_idempotency_key(request),
-        )
-        if not result.get("ok"):
-            raise HTTPException(404, detail="Correction case not found")
-        if action in {"apply", "rollback"}:
-            from superlocalmemory.core.mutations import purge_profile_context_cache
-
-            purge_profile_context_cache(engine, active_profile)
-        engine._hooks.run_post("update", hook_context)
-        return {"success": True, "correction_case": result}
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise _canonical_mutation_error(exc, "Correction review error")
-
-
-def _correction_case_response(case) -> dict[str, object]:
-    """Return review metadata only; correction ledgers never contain fact text."""
-    return {
-        "case_id": case.case_id,
-        "profile_id": case.profile_id,
-        "scope": case.scope,
-        "predecessor_fact_id": case.predecessor_fact_id,
-        "successor_fact_id": case.successor_fact_id,
-        "reason_code": case.reason_code,
-        "status": case.status,
-        "version": case.version,
-        "created_at": case.created_at,
-        "updated_at": case.updated_at,
-        "reviewed_at": case.reviewed_at,
-        "applied_at": case.applied_at,
-        "system_effective_at": case.system_effective_at,
-        "event_valid_from": case.event_valid_from,
-        "event_valid_until": case.event_valid_until,
-    }
-
-
-def _correction_store_for(engine, active_profile: str):
-    from superlocalmemory.storage.correction_cases import CorrectionCaseStore
-
-    return CorrectionCaseStore(
-        engine._db.db_path,
-        is_profile_active=lambda candidate: candidate == active_profile,
-        # Read operations never invoke this callback; writes use the daemon's
-        # canonical runtime, which derives the authenticated actor separately.
-        is_actor_trusted=lambda _actor: False,
-    )
-
-
-@router.get("/api/corrections")
-async def list_corrections(request: Request, limit: int = 100):
-    """List bounded review metadata for the active owning profile."""
-    try:
-        engine, active_profile, _context = _authorize_memory_mutation(
-            request, "update", "correction-list", run_pre_hook=False
-        )
-        cases = _correction_store_for(engine, active_profile).list_cases(active_profile, limit=limit)
-        return {"success": True, "corrections": [_correction_case_response(case) for case in cases]}
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise _canonical_mutation_error(exc, "Correction list error")
-
-
-@router.get("/api/corrections/{case_id}")
-async def get_correction(request: Request, case_id: str):
-    """Get one active-profile correction case without exposing raw memory text."""
-    try:
-        engine, active_profile, _context = _authorize_memory_mutation(
-            request, "update", case_id, run_pre_hook=False
-        )
-        case = _correction_store_for(engine, active_profile).get_case(case_id)
-        return {"success": True, "correction": _correction_case_response(case)}
-    except HTTPException:
-        raise
-    except Exception as exc:
-        from superlocalmemory.storage.correction_cases import CorrectionNotFoundError
-
-        if isinstance(exc, CorrectionNotFoundError):
-            raise HTTPException(404, detail="Correction case not found") from exc
-        raise _canonical_mutation_error(exc, "Correction lookup error")
-
-
-_VALID_SCOPES = ("personal", "shared", "global")
-
-
-@router.patch("/api/memories/{fact_id}/scope")
-async def set_memory_scope(request: Request, fact_id: str):
-    """Set a memory's scope (personal | shared | global) + shared_with.
-
-    Body: {"scope": "shared", "shared_with": "alice,bob"}. shared_with accepts a
-    comma-separated string or a list; it is stored as a JSON array so the
-    _scope_where LIKE match works. Mutation-authorized, and the fact must
-    belong to the active profile (a caller cannot re-scope another profile's
-    fact). This is the write side of multi-scope sharing from the dashboard.
-    """
-    try:
-        body = await request.json()
-        scope = (body.get("scope") or "").strip().lower()
-        if scope not in _VALID_SCOPES:
-            raise HTTPException(400, detail=f"scope must be one of {_VALID_SCOPES}")
-
-        raw_shared = body.get("shared_with", [])
-        if isinstance(raw_shared, str):
-            shared_list = [s.strip() for s in raw_shared.split(",") if s.strip()]
-        elif isinstance(raw_shared, list):
-            shared_list = [str(s).strip() for s in raw_shared if str(s).strip()]
-        else:
-            shared_list = []
-        if scope == "shared" and not shared_list:
-            raise HTTPException(
-                400, detail="shared scope requires at least one profile in shared_with")
-        # global/personal never carry a shared_with list.
-        if scope != "shared":
-            shared_list = []
-
-        engine, active_profile, hook_context = _authorize_memory_mutation(
-            request, "update", fact_id, run_pre_hook=False,
-        )
-        if scope in {"shared", "global"}:
-            from superlocalmemory.access.rbac import Permission
-            from superlocalmemory.server.rbac_enforce import require_permission
-
-            require_permission(request, Permission.SHARE, profile=active_profile)
-        engine._hooks.run_pre("update", hook_context)
-        result = _canonical_mutation_runtime(request).set_fact_scope(
-            active_profile,
-            fact_id,
-            scope,
-            shared_list,
-            idempotency_key=_mutation_idempotency_key(request),
-        )
-        if not result.get("ok"):
-            raise HTTPException(404, detail="Memory not found in this profile")
-        engine._hooks.run_post("update", hook_context)
-        return {
-            "success": True, "fact_id": fact_id, "scope": scope,
-            "shared_with": shared_list, "active_profile": active_profile,
-        }
-    except HTTPException:
-        raise
-    except Exception as exc:
-        raise _canonical_mutation_error(exc, "Scope update error")