adl-toolkit 0.0.0-stage → 0.1.3

package/adl_drift/cortex/memory.py

@@ -0,0 +1,1749 @@
+"""Cortex V2 memory layer.
+
+Persistent storage for approved patterns, tribal knowledge, and scan history.
+Uses SQLite for structured data and vector embeddings for semantic search.
+
+Equivalent to drift_core/src/cortex.rs.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import functools
+import gc
+import importlib.util
+import os
+import pickle
+import sqlite3
+import sys
+import json
+import hashlib
+import time
+from pathlib import Path
+from typing import Optional, List, Dict, Any, Iterable, Tuple
+from dataclasses import asdict
+from datetime import datetime
+
+from adl_drift.utils.types import Pattern, ProjectContext
+from adl_drift.graph.node import GraphNode, NodeType
+from adl_drift.graph.edges import GraphEdge, EdgeType
+from adl_drift.graph.builder import CallGraphBuilder, GRAPH_SCHEMA_VERSION
+
+# numpy is only needed by the optional embedding paths, but importing it at
+# module load costs ~0.2s on every CLI invocation; import it on first use.
+HAS_NUMPY = importlib.util.find_spec("numpy") is not None
+
+@contextlib.contextmanager
+def _gc_paused():
+    was_enabled = gc.isenabled()
+    gc.disable()
+    try:
+        yield
+    finally:
+        if was_enabled:
+            gc.enable()
+
+
+@functools.lru_cache(maxsize=None)
+def _snapshot_code_key() -> str:
+    """Identity of the code a pickled graph snapshot depends on.
+
+    A pickle silently mirrors the class layout that wrote it, so a snapshot
+    is only trusted while the graph package's own source, the interpreter,
+    networkx and the schema version are the ones that produced it — any
+    edit to those files (not just a GRAPH_SCHEMA_VERSION bump) falls back to
+    the row-by-row load, which then re-persists a fresh snapshot.
+    """
+    import networkx
+
+    digest = hashlib.sha256()
+    digest.update(
+        f"{GRAPH_SCHEMA_VERSION}|{pickle.HIGHEST_PROTOCOL}|{sys.version_info[:2]}|"
+        f"{networkx.__version__}".encode()
+    )
+    for module in ("adl_drift.graph.builder", "adl_drift.graph.node", "adl_drift.graph.edges"):
+        digest.update(Path(sys.modules[module].__file__).read_bytes())
+    return digest.hexdigest()
+
+
+# MCP_GRAPH_CACHE_PLAN.md Lớp 1: a source whose mtime lies within this many
+# seconds of the fingerprint's stat time may have been rewritten with the
+# same size/mtime, so a stat-based fingerprint match must be confirmed by a
+# content-hash classification for such files.
+GRAPH_CACHE_RACY_WINDOW_SECONDS = 2.0
+
+
+def _loads_metadata(raw: Optional[str]) -> Dict[str, Any]:
+    """Decode persisted metadata; most rows carry none, so skip the parser."""
+    if not raw or raw == "{}":
+        return {}
+    return json.loads(raw)
+
+
+class CortexMemory:
+    """Persistent memory for the analysis engine.
+
+    Tables:
+    - patterns: Approved/detected patterns with metadata
+    - tribal_knowledge: Human-written rules and explanations
+    - scan_history: Past analysis results
+    - embeddings: Vector representations for semantic search
+    """
+
+    def __init__(
+        self,
+        db_path: Optional[Path] = None,
+        embedder: Optional[Any] = None,
+    ):
+        if db_path is None:
+            # Default to platform-specific cache dir
+            import platformdirs
+            cache_dir = Path(platformdirs.user_cache_dir("adl-drift", "adl"))
+            db_path = cache_dir / "cortex.db"
+
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        # P2.3: anything with embed_single(text) -> 1-D float array works.
+        # None → lazily create an EmbeddingEngine iff sentence-transformers
+        # is installed (and DRIFT_EMBEDDINGS != 0); otherwise vector search
+        # stays off and search_similar uses the LIKE fallback.
+        self._embedder = embedder
+        self._embedder_resolved = embedder is not None
+        self._init_db()
+
+    @classmethod
+    def for_project(cls, project_root: Path) -> "CortexMemory":
+        project_root = Path(project_root)
+        return cls(project_root / ".adl-drift" / "cortex.db")
+
+    def _get_embedder(self) -> Optional[Any]:
+        """P2.3: resolve the embedding engine once (lazy, optional)."""
+        if self._embedder_resolved:
+            return self._embedder
+        self._embedder_resolved = True
+        if not HAS_NUMPY or os.environ.get("DRIFT_EMBEDDINGS", "1") == "0":
+            return None
+        from adl_drift.cortex.embeddings import (
+            EmbeddingEngine, HAS_SENTENCE_TRANSFORMERS,
+        )
+        # Without the real model EmbeddingEngine returns *random* vectors —
+        # storing those would poison search. Only wire it when genuine.
+        # Model load is best-effort: first use downloads from HuggingFace,  
+        # so an offline machine without a cached model must degrade to the
+        # LIKE fallback, not crash every store_pattern.
+        if HAS_SENTENCE_TRANSFORMERS:
+            try:
+                self._embedder = EmbeddingEngine()
+            except Exception:
+                self._embedder = None
+        return self._embedder
+
+    def _connect(self) -> sqlite3.Connection:
+        """Open a connection with the per-connection pragma ``_init_db`` intends.
+
+        ``journal_mode=WAL`` persists in the database file, but ``synchronous``
+        is per connection: without setting it here every other connection ran
+        at FULL and fsync()ed on each commit (~150ms per telemetry row on a
+        slow disk). NORMAL under WAL still survives an application crash; only
+        a power loss can lose the last committed transactions, never corrupt.
+        """
+        conn = sqlite3.connect(self.db_path)
+        conn.execute("PRAGMA synchronous=NORMAL")
+        return conn
+
+    def _init_db(self) -> None:
+        """Initialize SQLite schema."""
+        with self._connect() as conn:
+            conn.executescript("""
+                PRAGMA journal_mode=WAL;
+                PRAGMA synchronous=NORMAL;
+
+                CREATE TABLE IF NOT EXISTS patterns (
+                    id TEXT PRIMARY KEY,
+                    category TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    description TEXT,
+                    file_path TEXT,
+                    line INTEGER,
+                    confidence REAL,
+                    is_approved INTEGER DEFAULT 0,
+                    metadata TEXT,  -- JSON
+                    created_at TEXT,
+                    updated_at TEXT
+                );
+
+                CREATE TABLE IF NOT EXISTS tribal_knowledge (
+                    id TEXT PRIMARY KEY,
+                    topic TEXT NOT NULL,
+                    content TEXT NOT NULL,
+                    tags TEXT,  -- JSON array
+                    created_at TEXT,
+                    updated_at TEXT
+                );
+
+                CREATE TABLE IF NOT EXISTS scan_history (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    project_path TEXT,
+                    files_analyzed INTEGER,
+                    patterns_found INTEGER,
+                    scan_duration_ms REAL,
+                    results_json TEXT,
+                    scanned_at TEXT,
+                    lines_of_code INTEGER DEFAULT 0,
+                    non_blank_lines INTEGER DEFAULT 0,
+                    total_symbols INTEGER DEFAULT 0,
+                    total_functions INTEGER DEFAULT 0,
+                    total_classes INTEGER DEFAULT 0,
+                    total_variables INTEGER DEFAULT 0,
+                    total_modules INTEGER DEFAULT 0,
+                    entry_points INTEGER DEFAULT 0,
+                    calls_edges INTEGER DEFAULT 0,
+                    frameworks_json TEXT,
+                    patterns_by_category_json TEXT
+                );
+
+                CREATE TABLE IF NOT EXISTS embeddings (
+                    id TEXT PRIMARY KEY,
+                    source_type TEXT,  -- 'pattern', 'tribal', 'symbol'
+                    source_id TEXT,
+                    vector BLOB,  -- Serialized numpy array
+                    text TEXT,
+                    created_at TEXT
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_patterns_category ON patterns(category);
+                CREATE INDEX IF NOT EXISTS idx_patterns_approved ON patterns(is_approved);
+                CREATE INDEX IF NOT EXISTS idx_tribal_topic ON tribal_knowledge(topic);
+
+                CREATE TABLE IF NOT EXISTS graph_nodes (
+                    project_path TEXT NOT NULL,
+                    id TEXT NOT NULL,
+                    name TEXT NOT NULL,
+                    node_type TEXT NOT NULL,
+                    module TEXT NOT NULL,
+                    file_path TEXT NOT NULL,
+                    line INTEGER,
+                    column INTEGER,
+                    contained_in TEXT,
+                    is_async INTEGER DEFAULT 0,
+                    is_entry_point INTEGER DEFAULT 0,
+                    is_test INTEGER DEFAULT 0,
+                    decorators TEXT,
+                    docstring TEXT,
+                    signature TEXT,
+                    qualified_name TEXT,
+                    metadata TEXT,
+                    language TEXT NOT NULL DEFAULT 'python',
+                    metadata_json TEXT,
+                    PRIMARY KEY (project_path, id)
+                );
+
+                CREATE TABLE IF NOT EXISTS graph_edges (
+                    project_path TEXT NOT NULL,
+                    source TEXT NOT NULL,
+                    target TEXT NOT NULL,
+                    edge_type TEXT NOT NULL,
+                    file_path TEXT,
+                    line INTEGER,
+                    col INTEGER,
+                    confidence REAL DEFAULT 1.0,
+                    metadata TEXT,
+                    strategy TEXT,
+                    PRIMARY KEY (project_path, source, target, edge_type)
+                );
+
+                CREATE TABLE IF NOT EXISTS graph_edge_occurrences (
+                    project_path TEXT NOT NULL,
+                    source TEXT NOT NULL,
+                    target TEXT NOT NULL,
+                    edge_type TEXT NOT NULL,
+                    file_path TEXT NOT NULL,
+                    line INTEGER,
+                    col INTEGER,
+                    start_byte INTEGER NOT NULL,
+                    end_byte INTEGER NOT NULL,
+                    confidence REAL DEFAULT 1.0,
+                    metadata TEXT,
+                    strategy TEXT,
+                    PRIMARY KEY (
+                        project_path, source, target, edge_type,
+                        file_path, start_byte, end_byte
+                    )
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_graph_nodes_project ON graph_nodes(project_path);
+                CREATE INDEX IF NOT EXISTS idx_graph_edges_project ON graph_edges(project_path);
+                CREATE INDEX IF NOT EXISTS idx_graph_edge_occurrences_project
+                    ON graph_edge_occurrences(project_path);
+            """)
+            # Migration: add confidence column if missing (older DBs).
+            cols = {r[1] for r in conn.execute("PRAGMA table_info(graph_edges)").fetchall()}
+            if "confidence" not in cols:
+                conn.execute("ALTER TABLE graph_edges ADD COLUMN confidence REAL DEFAULT 1.0")
+            # Migration (P4.12): per-edge provenance metadata (JSON). NULL on
+            # old rows -> an empty dict on load; every non-Java edge stores it
+            # empty, so this is purely additive.
+            if "metadata" not in cols:
+                conn.execute("ALTER TABLE graph_edges ADD COLUMN metadata TEXT")
+            # Migration (P4.6 F-03): call-site column, disambiguates two
+            # same-named calls resolving to different targets on one line —
+            # see `GraphEdge.column`. Named `col` (not `column`) since the
+            # latter is a reserved SQL keyword. NULL on old rows is fine,
+            # same line-only fallback `TaintAnalyzer._resolve_callees`
+            # already had.
+            if "col" not in cols:
+                conn.execute("ALTER TABLE graph_edges ADD COLUMN col INTEGER")
+            if "strategy" not in cols:
+                conn.execute("ALTER TABLE graph_edges ADD COLUMN strategy TEXT")
+            # Migration (P1.10 step 3): qualified_name column. NULL on old
+            # rows is fine — GraphNode.__post_init__ re-derives it on load.
+            cols = {r[1] for r in conn.execute("PRAGMA table_info(graph_nodes)").fetchall()}
+            if "qualified_name" not in cols:
+                conn.execute("ALTER TABLE graph_nodes ADD COLUMN qualified_name TEXT")
+            # Migration (F-01): GraphNode.metadata (JSON) — was silently
+            # dropped on save/load, breaking P4.12 abstract-dispatch fan-out
+            # for nodes reloaded from a prior scan. NULL on old rows -> {}.
+            if "metadata" not in cols:
+                conn.execute("ALTER TABLE graph_nodes ADD COLUMN metadata TEXT")
+            if "language" not in cols:
+                conn.execute("ALTER TABLE graph_nodes ADD COLUMN language TEXT NOT NULL DEFAULT 'python'")
+            if "metadata_json" not in cols:
+                conn.execute("ALTER TABLE graph_nodes ADD COLUMN metadata_json TEXT")
+            if "is_test" not in cols:
+                conn.execute("ALTER TABLE graph_nodes ADD COLUMN is_test INTEGER DEFAULT 0")
+            # Migration (P7 continuation, GRAPH_SCHEMA_VERSION 28): symbol body
+            # end line, for snippet-sizing. NULL on old rows -> GraphNode's
+            # own end_line=0 default (adaptive sizing falls back to flat).
+            if "end_line" not in cols:
+                conn.execute("ALTER TABLE graph_nodes ADD COLUMN end_line INTEGER")
+            # P1.10 step 1: collision side table (auto-created, no migration
+            # risk). One row per displaced node, keyed by source location.
+            conn.executescript("""
+                CREATE TABLE IF NOT EXISTS node_collisions (
+                    project_path TEXT NOT NULL,
+                    file_path TEXT NOT NULL,
+                    line INTEGER NOT NULL,
+                    node_id TEXT NOT NULL,
+                    name TEXT,
+                    node_type TEXT,
+                    PRIMARY KEY (project_path, file_path, line)
+                );
+
+                -- Pickled CallGraphBuilder written alongside the row tables by
+                -- save_graph(); load_graph() prefers it (one blob read instead
+                -- of rebuilding ~20k objects from rows) whenever its code_key
+                -- still matches _snapshot_code_key(), else falls back to rows.
+                CREATE TABLE IF NOT EXISTS graph_snapshots (
+                    project_path TEXT PRIMARY KEY,
+                    code_key TEXT NOT NULL,
+                    snapshot BLOB NOT NULL
+                );
+            """)
+            conn.executescript("""
+
+                CREATE TABLE IF NOT EXISTS graph_metadata (
+                    project_path TEXT PRIMARY KEY,
+                    saved_at REAL
+                );
+
+                -- MCP_TOKEN_BUDGET_PLAN.md Lớp 2: drift_plan_change snapshots
+                -- (full caller / file sets) referenced by id from the compact
+                -- baseline the agent carries to drift_verify_change.
+                CREATE TABLE IF NOT EXISTS impact_baselines (
+                    id TEXT PRIMARY KEY,
+                    symbol TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    payload_json TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS file_metadata (
+                    project_path TEXT NOT NULL,
+                    file_path TEXT NOT NULL,
+                    content_hash TEXT NOT NULL,
+                    last_modified REAL,
+                    last_scanned TEXT,
+                    analysis_json TEXT,
+                    PRIMARY KEY (project_path, file_path)
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_file_metadata_project ON file_metadata(project_path);
+            """)
+            # Migration: add graph_version column if missing (older DBs).
+            # Old rows get NULL → version mismatch → cached graph invalidated
+            # on next load, forcing a rebuild with the current resolver.
+            cols = {r[1] for r in conn.execute("PRAGMA table_info(graph_metadata)").fetchall()}
+            if "graph_version" not in cols:
+                conn.execute("ALTER TABLE graph_metadata ADD COLUMN graph_version INTEGER")
+            if "module_owners" not in cols:
+                conn.execute("ALTER TABLE graph_metadata ADD COLUMN module_owners TEXT")
+            if "source_fingerprint" not in cols:
+                conn.execute("ALTER TABLE graph_metadata ADD COLUMN source_fingerprint TEXT")
+            if "backend_name" not in cols:
+                conn.execute("ALTER TABLE graph_metadata ADD COLUMN backend_name TEXT")
+            if "backend_version" not in cols:
+                conn.execute("ALTER TABLE graph_metadata ADD COLUMN backend_version INTEGER")
+            if "indexed_extensions" not in cols:
+                conn.execute("ALTER TABLE graph_metadata ADD COLUMN indexed_extensions TEXT")
+
+            # Migration: baseline metric columns on scan_history (additive defaults).
+            scan_cols = {r[1] for r in conn.execute("PRAGMA table_info(scan_history)").fetchall()}
+            for col, dtype in (
+                ("lines_of_code", "INTEGER DEFAULT 0"),
+                ("non_blank_lines", "INTEGER DEFAULT 0"),
+                ("total_symbols", "INTEGER DEFAULT 0"),
+                ("total_functions", "INTEGER DEFAULT 0"),
+                ("total_classes", "INTEGER DEFAULT 0"),
+                ("total_variables", "INTEGER DEFAULT 0"),
+                ("total_modules", "INTEGER DEFAULT 0"),
+                ("entry_points", "INTEGER DEFAULT 0"),
+                ("calls_edges", "INTEGER DEFAULT 0"),
+                ("frameworks_json", "TEXT"),
+                ("patterns_by_category_json", "TEXT"),
+            ):
+                if col not in scan_cols:
+                    conn.execute(f"ALTER TABLE scan_history ADD COLUMN {col} {dtype}")
+
+            # P2.18: def-use facts table (auto-created, no migration needed for fresh DBs)
+            conn.executescript("""
+                CREATE TABLE IF NOT EXISTS def_use_facts (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    project_path TEXT NOT NULL,
+                    function_id TEXT NOT NULL,
+                    binding_name TEXT NOT NULL,
+                    def_line INTEGER,
+                    def_col INTEGER,
+                    use_line INTEGER,
+                    use_col INTEGER,
+                    is_literal INTEGER DEFAULT 0,
+                    taint_source TEXT,
+                    created_at TEXT
+                );
+                CREATE INDEX IF NOT EXISTS idx_def_use_function
+                    ON def_use_facts(project_path, function_id);
+                CREATE INDEX IF NOT EXISTS idx_def_use_binding
+                    ON def_use_facts(project_path, binding_name);
+            """)
+            # P2.19: taint paths table (auto-created, no migration for fresh DBs)
+            conn.executescript("""
+                CREATE TABLE IF NOT EXISTS taint_paths (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    project_path TEXT NOT NULL,
+                    function_id TEXT NOT NULL,
+                    file_path TEXT,
+                    sink TEXT,
+                    sink_category TEXT,
+                    source_label TEXT,
+                    binding_name TEXT,
+                    sink_line INTEGER,
+                    sink_col INTEGER,
+                    chain TEXT,
+                    confidence REAL DEFAULT 0.9,
+                    cross_function INTEGER DEFAULT 0,
+                    created_at TEXT
+                );
+                CREATE INDEX IF NOT EXISTS idx_taint_function
+                    ON taint_paths(project_path, function_id);
+            """)
+
+            # MONITOR: per-tool-call telemetry for the project monitor UI.
+            # One row per MCP tool invocation, recording the tokens drift
+            # returned vs. an estimated read+grep baseline, plus the confidence
+            # profile of the answer. Powers monitor/ "tokens saved" + "confidence".
+            conn.executescript("""
+                CREATE TABLE IF NOT EXISTS tool_invocations (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    project_path TEXT,
+                    tool TEXT NOT NULL,
+                    target TEXT,
+                    args TEXT,                 -- JSON of selected params
+                    response_tokens INTEGER,   -- tokens drift returned
+                    baseline_tokens INTEGER,   -- est. read+grep tokens for same answer
+                    saved_tokens INTEGER,      -- baseline - response (>= 0)
+                    files_referenced INTEGER,
+                    result_count INTEGER,
+                    confidence_min REAL,
+                    confidence_avg REAL,
+                    confidence_max REAL,
+                    high_conf INTEGER DEFAULT 0,   -- >= 0.85
+                    med_conf INTEGER DEFAULT 0,    -- 0.6 .. 0.85
+                    low_conf INTEGER DEFAULT 0,    -- < 0.6
+                    duration_ms REAL,
+                    is_error INTEGER DEFAULT 0,
+                    created_at TEXT
+                );
+                CREATE INDEX IF NOT EXISTS idx_tool_invocations_project
+                    ON tool_invocations(project_path);
+                CREATE INDEX IF NOT EXISTS idx_tool_invocations_created
+                    ON tool_invocations(created_at);
+            """)
+
+    def store_invocation(self, record: Dict[str, Any]) -> None:
+        """MONITOR: append one tool-call telemetry row (best-effort).
+
+        ``record`` keys mirror the ``tool_invocations`` columns; missing keys
+        default sensibly. Never raises — telemetry must not break a tool call.
+        """
+        try:
+            with self._connect() as conn:
+                conn.execute("""
+                    INSERT INTO tool_invocations
+                    (project_path, tool, target, args, response_tokens,
+                     baseline_tokens, saved_tokens, files_referenced,
+                     result_count, confidence_min, confidence_avg, confidence_max,
+                     high_conf, med_conf, low_conf, duration_ms, is_error, created_at)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """, (
+                    record.get("project_path"),
+                    record.get("tool"),
+                    record.get("target"),
+                    json.dumps(record.get("args") or {}, default=str),
+                    int(record.get("response_tokens", 0)),
+                    int(record.get("baseline_tokens", 0)),
+                    int(record.get("saved_tokens", 0)),
+                    int(record.get("files_referenced", 0)),
+                    int(record.get("result_count", 0)),
+                    record.get("confidence_min"),
+                    record.get("confidence_avg"),
+                    record.get("confidence_max"),
+                    int(record.get("high_conf", 0)),
+                    int(record.get("med_conf", 0)),
+                    int(record.get("low_conf", 0)),
+                    record.get("duration_ms"),
+                    int(bool(record.get("is_error", False))),
+                    datetime.now().isoformat(),
+                ))
+        except Exception:
+            pass
+
+    def get_invocations(
+        self, project_path: Optional[str] = None, limit: int = 200
+    ) -> List[Dict[str, Any]]:
+        """MONITOR: most-recent telemetry rows, newest first."""
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            sql = "SELECT * FROM tool_invocations"
+            args: List[Any] = []
+            if project_path:
+                sql += " WHERE project_path = ?"
+                args.append(project_path)
+            sql += " ORDER BY id DESC LIMIT ?"
+            args.append(limit)
+            return [dict(r) for r in conn.execute(sql, args).fetchall()]
+
+    def get_invocation_stats(
+        self, project_path: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """MONITOR: cumulative aggregates across all telemetry rows."""
+        with self._connect() as conn:
+            where = ""
+            args: List[Any] = []
+            if project_path:
+                where = " WHERE project_path = ?"
+                args.append(project_path)
+            row = conn.execute(f"""
+                SELECT COUNT(*) AS calls,
+                       COALESCE(SUM(response_tokens), 0) AS response_tokens,
+                       COALESCE(SUM(baseline_tokens), 0) AS baseline_tokens,
+                       COALESCE(SUM(saved_tokens), 0) AS saved_tokens,
+                       COALESCE(SUM(high_conf), 0) AS high_conf,
+                       COALESCE(SUM(med_conf), 0) AS med_conf,
+                       COALESCE(SUM(low_conf), 0) AS low_conf
+                FROM tool_invocations{where}
+            """, args).fetchone()
+            return {
+                "calls": row[0], "response_tokens": row[1],
+                "baseline_tokens": row[2], "saved_tokens": row[3],
+                "high_conf": row[4], "med_conf": row[5], "low_conf": row[6],
+            }
+
+    def store_pattern(self, pattern: Pattern) -> str:
+        """Store a detected pattern. Returns the pattern ID."""
+        return self.store_patterns([pattern])[0]
+
+    def store_patterns(self, patterns: List[Pattern]) -> List[str]:
+        """Store multiple patterns in one connection/transaction.
+
+        P8: `store_pattern` previously opened its own `sqlite3.connect()` +
+        commit per call; scanning a corpus with tens of thousands of patterns
+        (e.g. one IMPORTS pattern per import statement) paid that connect+
+        commit overhead once per pattern. Batches share a single connection
+        and one `executemany` + commit instead.
+
+        Commit granularity note: callers must call this once per file (or a
+        small bounded group of files), not once for an entire multi-file
+        scan — `IncrementalScanner.store_result`/`store_file_metadata` commits
+        immediately after a file's patterns are persisted, and incremental
+        rescans use `file_metadata` (not the `patterns` table) to decide a
+        file is "already scanned". Batching all of a scan's patterns into one
+        end-of-scan transaction would invert that ordering: a crash after
+        `file_metadata` commits for N files but before one large `patterns`
+        transaction commits would permanently lose those N files' patterns
+        (they'd never be rescanned since their content hash didn't change).
+        Per-file batching preserves the existing crash-recovery invariant.
+        """
+        if not patterns:
+            return []
+        now = datetime.now().isoformat()
+        pattern_ids = [p.compute_hash() for p in patterns]
+        rows = [
+            (
+                pattern_id,
+                pattern.category.name,
+                pattern.name,
+                pattern.description,
+                str(pattern.file_path),
+                pattern.position.line,
+                pattern.confidence,
+                int(pattern.is_approved),
+                json.dumps(pattern.metadata),
+                now,
+                now,
+            )
+            for pattern_id, pattern in zip(pattern_ids, patterns)
+        ]
+        with self._connect() as conn:
+            conn.executemany("""
+                INSERT OR REPLACE INTO patterns
+                (id, category, name, description, file_path, line,
+                 confidence, is_approved, metadata, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, rows)
+
+        # P2.3: embed name+description for vector search (no-op when no
+        # embedder; skipped when the same text is already embedded, so
+        # re-scans don't pay the model cost again).
+        for pattern_id, pattern in zip(pattern_ids, patterns):
+            self._store_embedding(
+                "pattern", pattern_id, f"{pattern.name}: {pattern.description or ''}"
+            )
+
+        return pattern_ids
+
+    def _store_embedding(self, source_type: str, source_id: str, text: str) -> None:
+        """P2.3: persist an embedding row for `text` (best-effort, optional)."""
+        text = (text or "").strip()
+        if not text:
+            return
+        embedder = self._get_embedder()
+        if embedder is None:
+            return
+        emb_id = f"{source_type}:{source_id}"
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT text FROM embeddings WHERE id = ?", (emb_id,)
+            ).fetchone()
+            if row is not None and row[0] == text:
+                return
+            import numpy as np
+            vector = np.asarray(embedder.embed_single(text), dtype=np.float32)
+            conn.execute("""
+                INSERT OR REPLACE INTO embeddings
+                (id, source_type, source_id, vector, text, created_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+            """, (
+                emb_id, source_type, source_id, vector.tobytes(), text,
+                datetime.now().isoformat(),
+            ))
+
+    def get_pattern(self, pattern_id: str) -> Optional[Dict[str, Any]]:
+        """Fetch one pattern row by id (P2.11: drift_approve validation)."""
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            row = conn.execute(
+                "SELECT * FROM patterns WHERE id = ?", (pattern_id,)
+            ).fetchone()
+            return dict(row) if row else None
+
+    def approve_pattern(self, pattern_id: str) -> None:
+        """Mark a pattern as approved (intentional design choice)."""
+        with self._connect() as conn:
+            conn.execute(
+                "UPDATE patterns SET is_approved = 1, updated_at = ? WHERE id = ?",
+                (datetime.now().isoformat(), pattern_id)
+            )
+
+    def get_patterns(self, category: Optional[str] = None, approved_only: bool = False) -> List[Dict[str, Any]]:
+        """Retrieve patterns from memory."""
+        query = "SELECT * FROM patterns WHERE 1=1"
+        params = []
+
+        if category:
+            query += " AND category = ?"
+            params.append(category)
+        if approved_only:
+            query += " AND is_approved = 1"
+
+        query += " ORDER BY confidence DESC"
+
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            rows = conn.execute(query, params).fetchall()
+            return [dict(row) for row in rows]
+
+    def save_impact_baseline(self, payload: Dict[str, Any]) -> str:
+        """Persist a drift_plan_change snapshot; returns its id (content hash)."""
+        body = json.dumps(payload, sort_keys=True, default=str)
+        baseline_id = hashlib.sha256(body.encode()).hexdigest()[:16]
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO impact_baselines (id, symbol, created_at, payload_json) VALUES (?, ?, ?, ?)",
+                (baseline_id, str(payload.get("symbol", "")), datetime.now().isoformat(), body),
+            )
+        return baseline_id
+
+    def load_impact_baseline(self, baseline_id: str) -> Optional[Dict[str, Any]]:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT payload_json FROM impact_baselines WHERE id = ?", (baseline_id,)
+            ).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def add_tribal_knowledge(self, topic: str, content: str, tags: Optional[List[str]] = None) -> str:
+        """Store institutional knowledge (human-written rules)."""
+        knowledge_id = hashlib.sha256(f"{topic}:{content}".encode()).hexdigest()[:16]
+
+        with self._connect() as conn:
+            conn.execute("""
+                INSERT OR REPLACE INTO tribal_knowledge
+                (id, topic, content, tags, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+            """, (
+                knowledge_id,
+                topic,
+                content,
+                json.dumps(tags or []),
+                datetime.now().isoformat(),
+                datetime.now().isoformat(),
+            ))
+
+        self._store_embedding("tribal", knowledge_id, f"{topic}: {content}")
+
+        return knowledge_id
+
+    def get_tribal_knowledge(self, topic: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Retrieve tribal knowledge."""
+        query = "SELECT * FROM tribal_knowledge"
+        params = []
+        if topic:
+            query += " WHERE topic = ?"
+            params.append(topic)
+        query += " ORDER BY updated_at DESC"
+
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            rows = conn.execute(query, params).fetchall()
+            return [dict(row) for row in rows]
+
+    # ── P2.18: def-use facts ─────────────────────────────────────────────────
+
+    def store_def_use_facts(
+        self,
+        project_path: Path,
+        facts: "List[Any]",  # List[DefUseFact] — imported lazily to avoid circular
+    ) -> int:
+        """Persist a batch of DefUseFact objects. Returns rows inserted."""
+        if not facts:
+            return 0
+        ppath = str(project_path)
+        now = datetime.now().isoformat()
+        rows = []
+        for f in facts:
+            rows.append((
+                ppath,
+                f.function_id,
+                f.binding_name,
+                f.def_site.line,
+                f.def_site.column,
+                f.use_site.line,
+                f.use_site.column,
+                int(f.is_literal),
+                f.taint_source,
+                now,
+            ))
+        with self._connect() as conn:
+            # Replace existing facts for this function (full recompute on re-scan)
+            if rows:
+                fids = list({r[1] for r in rows})
+                conn.executemany(
+                    "DELETE FROM def_use_facts WHERE project_path=? AND function_id=?",
+                    [(ppath, fid) for fid in fids],
+                )
+            conn.executemany(
+                """INSERT INTO def_use_facts
+                   (project_path, function_id, binding_name,
+                    def_line, def_col, use_line, use_col,
+                    is_literal, taint_source, created_at)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                rows,
+            )
+        return len(rows)
+
+    def get_def_use_facts(
+        self,
+        project_path: Path,
+        function_id: str,
+        binding_name: Optional[str] = None,
+    ) -> "List[Any]":
+        """Return DefUseFact objects for a function (optionally filtered by name)."""
+        from adl_drift.graph.cfg import DefUseFact
+        from adl_drift.utils.types import SourcePosition
+
+        ppath = str(project_path)
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            if binding_name:
+                rows = conn.execute(
+                    """SELECT * FROM def_use_facts
+                       WHERE project_path=? AND function_id=? AND binding_name=?""",
+                    (ppath, function_id, binding_name),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM def_use_facts WHERE project_path=? AND function_id=?",
+                    (ppath, function_id),
+                ).fetchall()
+        out = []
+        for r in rows:
+            out.append(DefUseFact(
+                function_id=r["function_id"],
+                binding_name=r["binding_name"],
+                def_site=SourcePosition(r["def_line"] or 0, r["def_col"] or 0),
+                use_site=SourcePosition(r["use_line"] or 0, r["use_col"] or 0),
+                is_literal=bool(r["is_literal"]),
+                taint_source=r["taint_source"],
+            ))
+        return out
+
+    def delete_def_use_facts(self, project_path: Path, function_ids: List[str]) -> None:
+        """Remove def-use facts for re-scanned functions (called during incremental update)."""
+        if not function_ids:
+            return
+        ppath = str(project_path)
+        with self._connect() as conn:
+            conn.executemany(
+                "DELETE FROM def_use_facts WHERE project_path=? AND function_id=?",
+                [(ppath, fid) for fid in function_ids],
+            )
+
+    # ── P2.19: taint paths ───────────────────────────────────────────────────
+
+    def store_taint_paths(
+        self,
+        project_path: Path,
+        paths: "List[Any]",  # List[TaintPath] — imported lazily (avoid circular)
+        replace_function_ids: Optional[List[str]] = None,
+    ) -> int:
+        """Persist taint paths. Replaces paths for *replace_function_ids* first
+        (the set of functions just re-analyzed); when ``None``, replaces every
+        path for the project (full-scan recompute). Returns rows inserted."""
+        ppath = str(project_path)
+        now = datetime.now().isoformat()
+        with self._connect() as conn:
+            if replace_function_ids is None:
+                conn.execute("DELETE FROM taint_paths WHERE project_path=?", (ppath,))
+            elif replace_function_ids:
+                conn.executemany(
+                    "DELETE FROM taint_paths WHERE project_path=? AND function_id=?",
+                    [(ppath, fid) for fid in set(replace_function_ids)],
+                )
+            rows = [
+                (
+                    ppath, p.function_id, p.file_path, p.sink, p.sink_category,
+                    p.source_label, p.binding_name, p.sink_site.line, p.sink_site.column,
+                    json.dumps(p.chain), p.confidence, int(p.cross_function), now,
+                )
+                for p in paths
+            ]
+            if rows:
+                conn.executemany(
+                    """INSERT INTO taint_paths
+                       (project_path, function_id, file_path, sink, sink_category,
+                        source_label, binding_name, sink_line, sink_col,
+                        chain, confidence, cross_function, created_at)
+                       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                    rows,
+                )
+        return len(paths)
+
+    def get_taint_paths(
+        self, project_path: Path, function_id: Optional[str] = None
+    ) -> "List[Any]":
+        """Return TaintPath objects for a project (optionally one function)."""
+        from adl_drift.detectors.taint import TaintPath
+        from adl_drift.utils.types import SourcePosition
+
+        ppath = str(project_path)
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            if function_id:
+                rows = conn.execute(
+                    "SELECT * FROM taint_paths WHERE project_path=? AND function_id=?",
+                    (ppath, function_id),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM taint_paths WHERE project_path=?", (ppath,)
+                ).fetchall()
+        out = []
+        for r in rows:
+            try:
+                chain = json.loads(r["chain"]) if r["chain"] else []
+            except Exception:
+                chain = []
+            out.append(TaintPath(
+                function_id=r["function_id"],
+                file_path=r["file_path"] or "",
+                sink=r["sink"] or "",
+                sink_category=r["sink_category"] or "",
+                source_label=r["source_label"] or "",
+                binding_name=r["binding_name"],
+                sink_site=SourcePosition(r["sink_line"] or 0, r["sink_col"] or 0),
+                chain=chain,
+                confidence=r["confidence"] if r["confidence"] is not None else 0.9,
+                cross_function=bool(r["cross_function"]),
+            ))
+        return out
+
+    def store_scan(self, context: ProjectContext, duration_ms: float, results_json: str) -> int:
+        """Store scan history with project-size baseline metrics."""
+        with self._connect() as conn:
+            cursor = conn.execute("""
+                INSERT INTO scan_history
+                (project_path, files_analyzed, patterns_found, scan_duration_ms, results_json, scanned_at,
+                 lines_of_code, non_blank_lines, total_symbols, total_functions, total_classes,
+                 total_variables, total_modules, entry_points, calls_edges,
+                 frameworks_json, patterns_by_category_json)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, (
+                str(context.root_path),
+                context.files_analyzed,
+                context.total_patterns,
+                duration_ms,
+                results_json,
+                datetime.now().isoformat(),
+                context.lines_of_code,
+                context.non_blank_lines,
+                context.total_symbols,
+                context.total_functions,
+                context.total_classes,
+                context.total_variables,
+                context.total_modules,
+                context.entry_points,
+                context.calls_edges,
+                json.dumps(context.frameworks),
+                json.dumps(context.patterns_by_category),
+            ))
+            return cursor.lastrowid or 0
+
+    def get_scan_baseline(self, project_path: Path) -> Optional[Dict[str, Any]]:
+        """Return the most recent scan-history baseline for a project.
+
+        Returns None when no scan has been recorded. This is the cheap,
+        read-only source for the monitor's project-size card and for
+        ``drift_status`` baseline reporting.
+        """
+        proj = str(project_path.resolve())
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            row = conn.execute(
+                """SELECT files_analyzed, patterns_found, lines_of_code, non_blank_lines,
+                          total_symbols, total_functions, total_classes, total_variables,
+                          total_modules, entry_points, calls_edges, frameworks_json,
+                          patterns_by_category_json, scan_duration_ms, scanned_at
+                   FROM scan_history
+                   WHERE project_path = ?
+                   ORDER BY id DESC
+                   LIMIT 1""",
+                (proj,),
+            ).fetchone()
+        if row is None:
+            return None
+        return {
+            "files_analyzed": row["files_analyzed"] or 0,
+            "patterns_found": row["patterns_found"] or 0,
+            "lines_of_code": row["lines_of_code"] or 0,
+            "non_blank_lines": row["non_blank_lines"] or 0,
+            "total_symbols": row["total_symbols"] or 0,
+            "total_functions": row["total_functions"] or 0,
+            "total_classes": row["total_classes"] or 0,
+            "total_variables": row["total_variables"] or 0,
+            "total_modules": row["total_modules"] or 0,
+            "entry_points": row["entry_points"] or 0,
+            "calls_edges": row["calls_edges"] or 0,
+            "frameworks": json.loads(row["frameworks_json"] or "[]"),
+            "patterns_by_category": json.loads(row["patterns_by_category_json"] or "{}"),
+            "scan_duration_ms": row["scan_duration_ms"] or 0,
+            "scanned_at": row["scanned_at"],
+        }
+
+    # P2.20: every table that carries a project_path. Dead-project reap
+    # deletes a project's rows from all of them when the project root is gone.
+    _PROJECT_TABLES = (
+        "graph_nodes", "graph_edges", "graph_edge_occurrences",
+        "graph_metadata", "node_collisions",
+        "file_metadata", "def_use_facts", "taint_paths", "scan_history",
+    )
+    # Tables carrying a per-row file_path that the dead-file reap can check.
+    # `patterns` has no project_path, so it is reaped by file existence only.
+    _FILE_TABLES = ("patterns", "file_metadata")
+
+    def prune_database(
+        self,
+        *,
+        stale_before: Optional[str] = None,
+        include_approved: bool = False,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        """P2.20: reclaim space from stale rows. Three passes + VACUUM.
+
+        1. Dead-project reap (always): any `project_path` whose root no longer
+           exists on disk → delete that project's rows from every project table.
+        2. Dead-file reap (always): in the surviving rows, delete `patterns` /
+           `file_metadata` rows whose `file_path` is gone from disk.
+        3. Stale-pattern sweep (opt-in): when `stale_before` (an ISO timestamp
+           captured just before a fresh *full* scan) is given, delete
+           `patterns` rows whose file still exists but whose `updated_at`
+           predates the scan — i.e. the detector no longer emits them, so the
+           full scan never refreshed their row. Approved rows are skipped
+           unless `include_approved`.
+
+        Orphaned `embeddings` rows are removed after the pattern deletions.
+        Returns a per-table deleted-row report plus `bytes_freed`.
+        `dry_run` counts what would be deleted without writing.
+        """
+        report: Dict[str, Any] = {
+            "deleted": {},
+            "dead_projects": 0,
+            "dead_files": 0,
+            "stale_patterns": 0,
+            "bytes_freed": 0,
+            "dry_run": dry_run,
+        }
+        size_before = self.db_path.stat().st_size if self.db_path.exists() else 0
+
+        def _bump(table: str, n: int) -> None:
+            if n:
+                report["deleted"][table] = report["deleted"].get(table, 0) + n
+
+        with self._connect() as conn:
+            tables = {
+                r[0] for r in conn.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table'"
+                )
+            }
+
+            # ---- Pass 1: dead-project reap ----
+            dead_projects: set = set()
+            for table in self._PROJECT_TABLES:
+                if table not in tables:
+                    continue
+                for (proj,) in conn.execute(
+                    f"SELECT DISTINCT project_path FROM {table}"
+                ).fetchall():
+                    if proj and not Path(proj).exists():
+                        dead_projects.add(proj)
+            for table in self._PROJECT_TABLES:
+                if table not in tables or not dead_projects:
+                    continue
+                for proj in dead_projects:
+                    if dry_run:
+                        n = conn.execute(
+                            f"SELECT COUNT(*) FROM {table} WHERE project_path = ?",
+                            (proj,),
+                        ).fetchone()[0]
+                    else:
+                        n = conn.execute(
+                            f"DELETE FROM {table} WHERE project_path = ?", (proj,)
+                        ).rowcount
+                    _bump(table, n)
+            report["dead_projects"] = len(dead_projects)
+
+            # ---- Pass 2: dead-file reap ----
+            for table in self._FILE_TABLES:
+                if table not in tables:
+                    continue
+                rows = conn.execute(
+                    f"SELECT rowid, file_path FROM {table}"
+                ).fetchall()
+                dead_ids = [
+                    rid for rid, fp in rows
+                    if fp and not Path(fp).exists()
+                ]
+                report["dead_files"] += len(dead_ids)
+                if dead_ids and not dry_run:
+                    conn.executemany(
+                        f"DELETE FROM {table} WHERE rowid = ?",
+                        [(rid,) for rid in dead_ids],
+                    )
+                _bump(table, len(dead_ids))
+
+            # ---- Pass 3: stale-pattern sweep (opt-in) ----
+            if stale_before is not None and "patterns" in tables:
+                rows = conn.execute(
+                    "SELECT id, file_path, is_approved, updated_at FROM patterns"
+                ).fetchall()
+                stale = [
+                    pid for pid, fp, approved, updated in rows
+                    if (updated or "") < stale_before
+                    and fp and Path(fp).exists()
+                    and (include_approved or not approved)
+                ]
+                report["stale_patterns"] = len(stale)
+                if stale and not dry_run:
+                    conn.executemany(
+                        "DELETE FROM patterns WHERE id = ?",
+                        [(pid,) for pid in stale],
+                    )
+                _bump("patterns", len(stale))
+
+            # ---- Orphaned embeddings ----
+            if "embeddings" in tables and not dry_run:
+                n = conn.execute("""
+                    DELETE FROM embeddings
+                    WHERE source_type = 'pattern'
+                      AND source_id NOT IN (SELECT id FROM patterns)
+                """).rowcount
+                n += conn.execute("""
+                    DELETE FROM embeddings
+                    WHERE source_type = 'tribal'
+                      AND source_id NOT IN (SELECT id FROM tribal_knowledge)
+                """).rowcount
+                _bump("embeddings", n)
+
+        # ---- VACUUM (must run outside a transaction) ----
+        if not dry_run:
+            with self._connect() as conn:
+                conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+                conn.isolation_level = None
+                conn.execute("VACUUM")
+            size_after = self.db_path.stat().st_size if self.db_path.exists() else 0
+            report["bytes_freed"] = max(0, size_before - size_after)
+
+        return report
+
+    @classmethod
+    def _source_files(cls, project_path: Path):
+        from adl_drift.scanner.discovery import discover_file_groups
+
+        for files in discover_file_groups(project_path).values():
+            yield from files
+
+    @classmethod
+    def _source_state(
+        cls, project_path: Path, files: Optional[Iterable[Path]] = None,
+    ) -> tuple[float, str]:
+        """``(max_mtime, fingerprint)`` over the project's discovered sources.
+
+        ``files`` lets a caller that has already run discovery for the same
+        project (``MCPHandlers._build_full_graph``) reuse it instead of
+        walking the tree again (MCP_GRAPH_CACHE_PLAN.md Lớp 2). It must be
+        the ``discover_file_groups`` result for ``project_path``; the digest
+        is order-independent because the files are sorted here either way.
+        """
+        project_path = project_path.resolve()
+        fingerprint = hashlib.sha256()
+        max_mtime = 0.0
+        if files is None:
+            files = cls._source_files(project_path)
+        for file_path in sorted(files):
+            try:
+                stat = file_path.stat()
+            except OSError:
+                continue
+            max_mtime = max(max_mtime, stat.st_mtime)
+            relative = file_path.relative_to(project_path).as_posix()
+            fingerprint.update(
+                f"{relative}\0{stat.st_size}\0{stat.st_mtime_ns}\n".encode()
+            )
+        return max_mtime, fingerprint.hexdigest()
+
+    def save_graph(
+        self, project_path: Path, builder: CallGraphBuilder,
+        files: Optional[Iterable[Path]] = None,
+    ) -> None:
+        """Persist a CallGraphBuilder to SQLite for fast reload.
+
+        ``files`` is forwarded to ``_source_state`` so a caller that already
+        discovered the project's sources does not walk the tree again.
+        """
+        proj = str(project_path.resolve())
+        with self._connect() as conn:
+            conn.execute("DELETE FROM graph_edges WHERE project_path = ?", (proj,))
+            conn.execute("DELETE FROM graph_edge_occurrences WHERE project_path = ?", (proj,))
+            conn.execute("DELETE FROM graph_nodes WHERE project_path = ?", (proj,))
+            conn.execute("DELETE FROM node_collisions WHERE project_path = ?", (proj,))
+            conn.execute("DELETE FROM graph_snapshots WHERE project_path = ?", (proj,))
+
+            # Batched inserts: a persisted Java corpus holds hundreds of
+            # thousands of rows, and one execute() per row dominated the
+            # dependency-scoped incremental update (P7 profile).
+            def _node_rows():
+                for node in builder._nodes.values():
+                    metadata_json = json.dumps(node.metadata)
+                    yield (
+                        proj, node.id, node.name, node.node_type.name, node.module,
+                        node.file_path, node.line, node.column, node.contained_in,
+                        int(node.is_async), int(node.is_entry_point), int(node.is_test),
+                        json.dumps(node.decorators), node.docstring, node.signature,
+                        node.qualified_name,
+                        metadata_json if node.metadata else None,
+                        node.language, metadata_json, node.end_line,
+                    )
+
+            conn.executemany("""
+                INSERT INTO graph_nodes
+                (project_path, id, name, node_type, module, file_path, line, column,
+                 contained_in, is_async, is_entry_point, is_test, decorators, docstring, signature,
+                 qualified_name, metadata, language, metadata_json, end_line)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, _node_rows())
+
+            # P1.10 step 1: persist the collision tripwire's side table so the
+            # signal survives across sessions (drift_status surfaces the count).
+            for (file_path, line), displaced in builder.node_collisions.items():
+                conn.execute("""
+                    INSERT OR REPLACE INTO node_collisions
+                    (project_path, file_path, line, node_id, name, node_type)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                """, (
+                    proj, file_path, line, displaced.id, displaced.name,
+                    displaced.node_type.name,
+                ))
+
+            conn.executemany("""
+                INSERT INTO graph_edges
+                (project_path, source, target, edge_type, file_path, line, col, confidence, metadata, strategy)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, (
+                (
+                    proj, edge.source, edge.target, edge.edge_type.name,
+                    edge.file_path, edge.line, edge.column, float(edge.confidence),
+                    json.dumps(edge.metadata) if edge.metadata else None,
+                    edge.strategy,
+                )
+                for edge in builder._edges
+            ))
+
+            conn.executemany("""
+                INSERT INTO graph_edge_occurrences
+                (project_path, source, target, edge_type, file_path, line, col,
+                 start_byte, end_byte, confidence, metadata, strategy)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """, (
+                (
+                    proj, edge.source, edge.target, edge.edge_type.name,
+                    edge.file_path or "", edge.line, edge.column,
+                    edge.start_byte if edge.start_byte is not None else -1,
+                    edge.end_byte if edge.end_byte is not None else -1,
+                    float(edge.confidence),
+                    json.dumps(edge.metadata) if edge.metadata else None,
+                    edge.strategy,
+                )
+                for edge in builder._edge_occurrences
+            ))
+
+            max_mtime, source_fingerprint = self._source_state(project_path, files)
+            conn.execute(
+                "INSERT OR REPLACE INTO graph_metadata "
+                "(project_path, saved_at, graph_version, module_owners, source_fingerprint, "
+                "backend_name, backend_version, indexed_extensions) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    proj,
+                    max_mtime,
+                    GRAPH_SCHEMA_VERSION,
+                    json.dumps({k: sorted(v) for k, v in builder._module_owners.items()}),
+                    source_fingerprint,
+                    ",".join(sorted(
+                        builder.backend_names
+                        or {node.language for node in builder._nodes.values()}
+                    )),
+                    GRAPH_SCHEMA_VERSION,
+                    json.dumps(sorted(
+                        builder.indexed_extensions
+                        or {
+                            Path(node.file_path).suffix
+                            for node in builder._nodes.values()
+                            if node.file_path
+                        }
+                    )),
+                ),
+            )
+            conn.execute(
+                "INSERT OR REPLACE INTO graph_snapshots (project_path, code_key, snapshot) "
+                "VALUES (?, ?, ?)",
+                (
+                    proj, _snapshot_code_key(),
+                    sqlite3.Binary(pickle.dumps(builder, protocol=pickle.HIGHEST_PROTOCOL)),
+                ),
+            )
+
+    def get_graph_metadata(self, project_path: Path) -> Optional[Dict[str, Any]]:
+        """P2.11 (drift_status): persisted-graph facts without loading or
+        invalidating anything. Returns None when no graph is saved.
+        """
+        proj = str(project_path.resolve())
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            meta = conn.execute(
+                "SELECT saved_at, graph_version, backend_name, backend_version, indexed_extensions "
+                "FROM graph_metadata WHERE project_path = ?",
+                (proj,)
+            ).fetchone()
+            if meta is None:
+                return None
+            node_types = dict(conn.execute(
+                "SELECT node_type, COUNT(*) FROM graph_nodes WHERE project_path = ? GROUP BY node_type",
+                (proj,)
+            ).fetchall())
+            edge_types = dict(conn.execute(
+                "SELECT edge_type, COUNT(*) FROM graph_edges WHERE project_path = ? GROUP BY edge_type",
+                (proj,)
+            ).fetchall())
+            occurrence_count = conn.execute(
+                "SELECT COUNT(*) FROM graph_edge_occurrences WHERE project_path = ?",
+                (proj,),
+            ).fetchone()
+            files = conn.execute(
+                "SELECT COUNT(*), MAX(last_scanned) FROM file_metadata WHERE project_path = ?",
+                (proj,)
+            ).fetchone()
+            collisions = conn.execute(
+                "SELECT COUNT(*) FROM node_collisions WHERE project_path = ?",
+                (proj,)
+            ).fetchone()
+            result = {
+                "saved_at": meta["saved_at"],
+                "graph_version": meta["graph_version"],
+                "backend_name": meta["backend_name"],
+                "backend_version": meta["backend_version"],
+                "indexed_extensions": json.loads(meta["indexed_extensions"]) if meta["indexed_extensions"] else [],
+                "total_nodes": sum(node_types.values()),
+                "total_edges": sum(edge_types.values()),
+                "total_edge_occurrences": occurrence_count[0] if occurrence_count else 0,
+                "node_types": node_types,
+                "edge_types": edge_types,
+                "files_indexed": files[0] or 0,
+                "last_scanned": files[1],
+                "node_collisions": collisions[0] or 0,
+            }
+            baseline = self.get_scan_baseline(project_path)
+            if baseline:
+                result["baseline"] = baseline
+            return result
+
+    def get_source_fingerprint(self, project_path: Path) -> Optional[str]:
+        """The persisted graph's source fingerprint (``_source_state``), or
+        ``None`` when no graph is saved. Reads one row and invalidates nothing.
+        """
+        proj = str(project_path.resolve())
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT source_fingerprint FROM graph_metadata WHERE project_path = ?",
+                (proj,),
+            ).fetchone()
+        return row[0] if row else None
+
+    def load_graph(
+        self, project_path: Path, *, allow_stale: bool = False,
+        files: Optional[Iterable[Path]] = None,
+        fingerprint: Optional[str] = None,
+    ) -> Optional[CallGraphBuilder]:
+        """Load a persisted graph.
+
+        ``allow_stale`` is for the incremental builder only.  It first
+        classifies source changes and then removes/rebuilds the invalidated
+        scope itself; discarding the snapshot here would make every edit a
+        full rebuild.  Ordinary readers retain the strict fingerprint check.
+
+        ``files`` is the caller's already-discovered source list for the
+        fingerprint check (see ``_source_state``); without it the tree is
+        walked a second time on every no-change query. ``fingerprint`` is a
+        ``_source_state`` digest the caller already computed for the same
+        sources, so the files are not stat()ed a second time either.
+
+        Runs with the cyclic GC paused: materialising a large graph (JUnit5:
+        ~500k objects) otherwise triggers full collections every few
+        thousand allocations, which more than doubled the load time.
+        """
+        with _gc_paused():
+            return self._load_graph(
+                project_path, allow_stale=allow_stale, files=files, fingerprint=fingerprint,
+            )
+
+    def _load_graph(
+        self, project_path: Path, *, allow_stale: bool,
+        files: Optional[Iterable[Path]], fingerprint: Optional[str],
+    ) -> Optional[CallGraphBuilder]:
+        proj = str(project_path.resolve())
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            row = conn.execute(
+                "SELECT COUNT(*) as cnt FROM graph_nodes WHERE project_path = ?",
+                (proj,)
+            ).fetchone()
+            if row is None or row["cnt"] == 0:
+                return None
+
+            # Staleness check: invalidate when any supported source changed.
+            meta = conn.execute(
+                "SELECT saved_at, graph_version, module_owners, source_fingerprint, "
+                "backend_name, backend_version, indexed_extensions "
+                "FROM graph_metadata WHERE project_path = ?",
+                (proj,)
+            ).fetchone()
+            if meta is None:
+                return None
+
+            # Version check: graph persisted by an older resolver (or a DB
+            # predating version stamps → NULL) may contain edges the current
+            # resolver would not emit. Invalidate so the graph self-heals.
+            if (
+                meta["graph_version"] != GRAPH_SCHEMA_VERSION
+                or meta["module_owners"] is None
+                or meta["source_fingerprint"] is None
+                or meta["backend_name"] is None
+                or meta["backend_version"] != GRAPH_SCHEMA_VERSION
+                or meta["indexed_extensions"] is None
+            ):
+                conn.execute("DELETE FROM graph_edges WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM graph_edge_occurrences WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM graph_nodes WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM graph_metadata WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM node_collisions WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM graph_snapshots WHERE project_path = ?", (proj,))
+                return None
+
+            if not allow_stale and fingerprint is None:
+                fingerprint = self._source_state(project_path, files)[1]
+            if not allow_stale and fingerprint != meta["source_fingerprint"]:
+                conn.execute("DELETE FROM graph_edges WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM graph_edge_occurrences WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM graph_nodes WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM graph_metadata WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM node_collisions WHERE project_path = ?", (proj,))
+                conn.execute("DELETE FROM graph_snapshots WHERE project_path = ?", (proj,))
+                return None
+
+            snapshot = conn.execute(
+                "SELECT code_key, snapshot FROM graph_snapshots WHERE project_path = ?",
+                (proj,),
+            ).fetchone()
+            if snapshot is not None and snapshot["code_key"] == _snapshot_code_key():
+                builder = self._restore_snapshot(snapshot["snapshot"], project_path)
+                if builder is not None:
+                    return builder
+
+            # Incremental updates add newly parsed files to this restored
+            # builder. Preserve the root used by a fresh build so module
+            # namespace selection (notably mixed-language Java projects) is
+            # identical to a full rebuild.
+            builder = CallGraphBuilder(project_root=project_path)
+            builder.backend_names = set(meta["backend_name"].split(","))
+            builder.indexed_extensions = set(json.loads(meta["indexed_extensions"]))
+            builder._module_owners = {
+                module_id: set(owners)
+                for module_id, owners in json.loads(meta["module_owners"]).items()
+            }
+
+            rows = conn.execute(
+                "SELECT * FROM graph_nodes WHERE project_path = ?",
+                (proj,)
+            ).fetchall()
+            keys = rows[0].keys() if rows else []
+            for row in rows:
+                node = GraphNode(
+                    id=row["id"],
+                    name=row["name"],
+                    node_type=NodeType[row["node_type"]],
+                    module=row["module"],
+                    file_path=row["file_path"] or "",
+                    line=row["line"] or 0,
+                    column=row["column"] or 0,
+                    end_line=(row["end_line"] or 0) if "end_line" in keys else 0,
+                    qualified_name=(row["qualified_name"] or "") if "qualified_name" in keys else "",
+                    contained_in=row["contained_in"],
+                    is_async=bool(row["is_async"]),
+                    is_entry_point=bool(row["is_entry_point"]),
+                    is_test=bool(row["is_test"]),
+                    decorators=json.loads(row["decorators"]) if row["decorators"] else [],
+                    docstring=row["docstring"],
+                    signature=row["signature"],
+                    language=row["language"] or "python",
+                    metadata=_loads_metadata(row["metadata"] or row["metadata_json"]),
+                )
+                builder._add_node(node)
+
+            # P1.10: restore the collision side table alongside the nodes.
+            for row in conn.execute(
+                "SELECT * FROM node_collisions WHERE project_path = ?", (proj,)
+            ).fetchall():
+                builder.node_collisions[(row["file_path"], row["line"])] = GraphNode(
+                    id=row["node_id"],
+                    name=row["name"] or "",
+                    node_type=NodeType[row["node_type"]] if row["node_type"] else NodeType.FUNCTION,
+                    module="",
+                    file_path=row["file_path"],
+                    line=row["line"],
+                    column=0,
+                )
+
+            rows = conn.execute(
+                "SELECT * FROM graph_edges WHERE project_path = ?",
+                (proj,)
+            ).fetchall()
+            for row in rows:
+                keys = row.keys()
+                edge = GraphEdge(
+                    source=row["source"],
+                    target=row["target"],
+                    edge_type=EdgeType[row["edge_type"]],
+                    file_path=row["file_path"],
+                    line=row["line"],
+                    column=row["col"] if "col" in keys else None,
+                    confidence=float(row["confidence"]) if "confidence" in keys and row["confidence"] is not None else 1.0,
+                    metadata=_loads_metadata(row["metadata"] if "metadata" in keys else None),
+                    strategy=row["strategy"] if "strategy" in keys else None,
+                )
+                builder._add_edge(edge)
+                if edge.edge_type == EdgeType.CALLS:
+                    if edge.source in builder._nodes:
+                        builder._nodes[edge.source].calls.add(edge.target)
+                    if edge.target in builder._nodes:
+                        builder._nodes[edge.target].called_by.add(edge.source)
+
+            for row in conn.execute(
+                "SELECT * FROM graph_edge_occurrences WHERE project_path = ?",
+                (proj,),
+            ).fetchall():
+                edge = GraphEdge(
+                    source=row["source"],
+                    target=row["target"],
+                    edge_type=EdgeType[row["edge_type"]],
+                    file_path=row["file_path"] or None,
+                    line=row["line"],
+                    column=row["col"],
+                    start_byte=None if row["start_byte"] == -1 else row["start_byte"],
+                    end_byte=None if row["end_byte"] == -1 else row["end_byte"],
+                    confidence=float(row["confidence"]),
+                    metadata=_loads_metadata(row["metadata"]),
+                    strategy=row["strategy"],
+                )
+                builder._record_edge_occurrence(edge)
+
+            if self._looks_like_java_graph(builder):
+                from adl_drift.lang.java.resolver import default_java_resolver_config
+                builder.resolver_config = default_java_resolver_config()
+
+            return builder
+
+    def _restore_snapshot(
+        self, blob: bytes, project_path: Path,
+    ) -> Optional[CallGraphBuilder]:
+        """Unpickle a ``graph_snapshots`` row into the state ``load_graph``'s
+        row-by-row path produces; ``None`` (→ row fallback) on any failure."""
+        try:
+            builder = pickle.loads(blob)
+        except Exception:
+            return None
+        if not isinstance(builder, CallGraphBuilder):
+            return None
+        builder.project_root = Path(project_path).resolve()
+        if self._looks_like_java_graph(builder):
+            from adl_drift.lang.java.resolver import default_java_resolver_config
+            builder.resolver_config = default_java_resolver_config()
+        return builder
+
+    @staticmethod
+    def _looks_like_java_graph(builder: CallGraphBuilder) -> bool:
+        """Best-effort resolver restoration for persisted Java graphs."""
+        for node in builder._nodes.values():
+            if Path(node.file_path).suffix == ".java":
+                return True
+            if any(str(key).startswith("java_") for key in node.metadata):
+                return True
+        return False
+
+    def store_file_metadata(
+        self,
+        project_path: Path,
+        file_path: Path,
+        content_hash: str,
+        last_modified: float,
+        analysis_json: str,
+    ) -> None:
+        """Store or update metadata for a single file."""
+        self.store_files_metadata(project_path, [(file_path, content_hash, last_modified, analysis_json)])
+
+    def store_files_metadata(
+        self,
+        project_path: Path,
+        entries: List[Tuple[Path, str, float, str]],
+    ) -> None:
+        """Store or update metadata for multiple files in one connection/transaction.
+
+        P8 Phase 3 follow-up: `store_file_metadata` previously opened its own
+        `sqlite3.connect()` + commit per file — every scanned file pays that
+        overhead once, on top of the one `store_patterns` already batches.
+        Same commit-granularity contract as `store_patterns`: a file's
+        `patterns` rows must already be committed before that file's entry is
+        included here (incremental rescans decide "already scanned" from
+        `file_metadata`, not `patterns`; committing metadata ahead of a file's
+        patterns would let a crash between the two permanently orphan that
+        file's patterns — see `store_patterns` docstring). Callers only ever
+        move this call *later* relative to the existing per-file
+        `store_patterns` call, never earlier, so that invariant still holds
+        batched across many files: the worst a crash mid-batch can do is
+        leave those files' `file_metadata` uncommitted, which just means they
+        get rescanned (idempotent — `store_patterns` keys patterns by content
+        hash) rather than silently losing data.
+        """
+        if not entries:
+            return
+        proj = str(project_path.resolve())
+        now = datetime.now().isoformat()
+        rows = [
+            (proj, str(file_path.resolve()), content_hash, last_modified, now, analysis_json)
+            for file_path, content_hash, last_modified, analysis_json in entries
+        ]
+        with self._connect() as conn:
+            conn.executemany("""
+                INSERT OR REPLACE INTO file_metadata
+                (project_path, file_path, content_hash, last_modified, last_scanned, analysis_json)
+                VALUES (?, ?, ?, ?, ?, ?)
+            """, rows)
+
+    def get_file_metadata(self, project_path: Path, file_path: Path) -> Optional[Dict[str, Any]]:
+        """Retrieve metadata for a single file."""
+        proj = str(project_path.resolve())
+        fpath = str(file_path.resolve())
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            row = conn.execute(
+                "SELECT * FROM file_metadata WHERE project_path = ? AND file_path = ?",
+                (proj, fpath),
+            ).fetchone()
+            return dict(row) if row else None
+
+    def get_all_file_metadata(self, project_path: Path) -> List[Dict[str, Any]]:
+        """Retrieve metadata for all files in a project."""
+        proj = str(project_path.resolve())
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            rows = conn.execute(
+                "SELECT * FROM file_metadata WHERE project_path = ?",
+                (proj,),
+            ).fetchall()
+            return [dict(row) for row in rows]
+
+    def prune_file_metadata(self, project_path: Path, current_files: set) -> None:
+        """Remove metadata for files that no longer exist in the project."""
+        proj = str(project_path.resolve())
+        with self._connect() as conn:
+            # SQLite doesn't directly support set operations, so we delete
+            # rows whose file_path is NOT IN the current set.
+            if not current_files:
+                conn.execute(
+                    "DELETE FROM file_metadata WHERE project_path = ?",
+                    (proj,),
+                )
+                return
+            placeholders = ",".join("?" * len(current_files))
+            conn.execute(
+                f"DELETE FROM file_metadata WHERE project_path = ? AND file_path NOT IN ({placeholders})",
+                (proj, *current_files),
+            )
+
+    def search_similar(self, query: str, limit: int = 5) -> List[Dict[str, Any]]:
+        """Semantic search over patterns and knowledge (P2.3).
+
+        When an embedding engine is available and vectors have been stored,
+        embeds the query and ranks stored embeddings by cosine similarity
+        (numpy brute force — the table holds at most a few thousand rows,
+        so a vector index would be overkill). Each hit carries a
+        ``similarity`` score. Falls back to SQLite LIKE text search when
+        embeddings are unavailable or the table is empty.
+        """
+        vector_hits = self._search_similar_vectors(query, limit)
+        if vector_hits is not None:
+            return vector_hits
+        return self._search_similar_like(query, limit)
+
+    def _search_similar_vectors(
+        self, query: str, limit: int
+    ) -> Optional[List[Dict[str, Any]]]:
+        """Cosine-similarity search; None → caller should use LIKE fallback."""
+        embedder = self._get_embedder()
+        if embedder is None:
+            return None
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            rows = conn.execute(
+                "SELECT id, source_type, source_id, vector FROM embeddings "
+                "WHERE source_type IN ('pattern', 'tribal')"
+            ).fetchall()
+            if not rows:
+                return None
+            import numpy as np
+            qvec = np.asarray(embedder.embed_single(query), dtype=np.float32)
+            qnorm = float(np.linalg.norm(qvec))
+            if qnorm == 0.0:
+                return None
+            scored: List[tuple] = []
+            for row in rows:
+                vec = np.frombuffer(row["vector"], dtype=np.float32)
+                if vec.shape != qvec.shape:
+                    continue  # stored by a different model — ignore
+                denom = qnorm * float(np.linalg.norm(vec))
+                if denom == 0.0:
+                    continue
+                scored.append((
+                    float(np.dot(qvec, vec)) / denom,
+                    row["source_type"], row["source_id"],
+                ))
+            scored.sort(key=lambda t: t[0], reverse=True)
+
+            out: List[Dict[str, Any]] = []
+            for sim, source_type, source_id in scored[:limit]:
+                if source_type == "pattern":
+                    hit = conn.execute(
+                        "SELECT * FROM patterns WHERE id = ?", (source_id,)
+                    ).fetchone()
+                    if hit is None:
+                        continue
+                    d = dict(hit)
+                else:  # tribal — map to the pattern-shaped dict the LIKE path emits
+                    hit = conn.execute(
+                        "SELECT * FROM tribal_knowledge WHERE id = ?", (source_id,)
+                    ).fetchone()
+                    if hit is None:
+                        continue
+                    d = {
+                        "id": hit["id"], "category": hit["topic"],
+                        "name": hit["topic"], "description": hit["content"],
+                        "file_path": None, "line": None, "confidence": 1.0,
+                        "is_approved": 1, "metadata": None,
+                        "created_at": hit["created_at"],
+                        "updated_at": hit["updated_at"],
+                    }
+                d["similarity"] = sim
+                out.append(d)
+            return out
+
+    def _search_similar_like(self, query: str, limit: int) -> List[Dict[str, Any]]:
+        """Plain text LIKE search (pre-P2.3 behavior, kept as fallback)."""
+        with self._connect() as conn:
+            conn.row_factory = sqlite3.Row
+            # Simple text search fallback
+            rows = conn.execute("""
+                SELECT * FROM patterns 
+                WHERE name LIKE ? OR description LIKE ?
+                UNION ALL
+                SELECT id, topic as category, topic as name, content as description, 
+                       NULL as file_path, NULL as line, 1.0 as confidence, 
+                       1 as is_approved, NULL as metadata, created_at, updated_at
+                FROM tribal_knowledge
+                WHERE topic LIKE ? OR content LIKE ?
+                LIMIT ?
+            """, (f"%{query}%", f"%{query}%", f"%{query}%", f"%{query}%", limit)).fetchall()
+            return [dict(row) for row in rows]