seam-code 0.3.0__py3-none-any.whl

seam/analysis/relevance.py

@@ -0,0 +1,155 @@
+"""Relevance ranking + self-reference classification for seam_impact output (E2/E3).
+
+LEAF MODULE — pure functions over plain dicts/strings. Imports only stdlib.
+No database access, no config, never raises. Mirrors the leaf discipline of
+seam/query/names.py and seam/analysis/builtins.py so the ranking rules can be
+unit-tested exhaustively without fixtures.
+
+WHY this module exists (the usability gap it closes):
+  When seam_impact analyses a CLASS, expand_impact_seeds fans the seed out to
+  every member, so the upstream walk surfaces the class's OWN sibling methods
+  (Foo.a "depends on" Foo.b) as direct dependents. Alphabetical ordering floats
+  these self-references above the EXTERNAL callers an agent actually cares about,
+  and under the per-tier cap the externals fall off the bottom. The 2026-06-07
+  neutral re-benchmark confirmed this empirically: recall improved (more real
+  dependents found) but usability did not, because the right answer was below the
+  cut line. This module ranks external dependents ahead of self-references BEFORE
+  the cap, so the cap drops self-refs first — exactly as the handler already drops
+  test dependents before production ones.
+
+Definitions:
+  container       — the class/struct a symbol belongs to. Derived from a qualified
+                    name's first segment ("Foo.bar" -> "Foo"; "pkg.Foo.bar" -> "pkg").
+  self-reference  — an entry that belongs to the target's own container (the target
+                    class itself, or any of its members). These are the entries an
+                    agent is already editing when they change the target.
+
+Conservatism contract (carried from the rest of the codebase):
+  When classification is uncertain, treat the entry as EXTERNAL. Never hide a real
+  external dependent by mis-flagging it self-ref. Never raise on the read path.
+"""
+
+from typing import Any
+
+
+def owning_container(name: str) -> str | None:
+    """Return the container segment of a qualified symbol name, or None if bare.
+
+    The container is everything before the LAST dot — consistent with bare_name()
+    in seam/query/names.py, which takes everything after the last dot.
+
+    Examples:
+        "Foo.bar"      -> "Foo"
+        "pkg.Foo.bar"  -> "pkg.Foo"
+        "bar"          -> None        (no dot — a bare name has no container)
+        ""             -> None        (empty)
+        ".bar"         -> None        (leading dot — empty container is not a container)
+        "Foo."         -> "Foo"       (trailing dot — degenerate but container is "Foo")
+
+    WHY everything-before-last-dot (not first segment):
+      Symbols are stored as "Container.member". For a deeply-qualified name like
+      "pkg.Foo.bar" the member is "bar" and its container is "pkg.Foo" — matching
+      how get_member_names builds "Class." prefixes. Using the first segment would
+      misclassify members of a dotted-package container.
+
+    Never raises.
+    """
+    if not name or "." not in name:
+        return None
+    prefix, _, _ = name.rpartition(".")
+    # A leading-dot name (".bar") has an empty prefix → not a real container.
+    return prefix or None
+
+
+def classify_self_ref(
+    entry_name: str,
+    container: str | None,
+    self_names: set[str],
+) -> bool:
+    """Return True when an impact entry belongs to the target's own container.
+
+    An entry is a self-reference when EITHER:
+      1. Its name is in self_names (the container itself or a bare member name), OR
+      2. Its owning container equals the target container (catches every qualified
+         member form — "Foo.bar" — regardless of whether Tier B inference qualified
+         the edge target).
+
+    The two checks are complementary: the owning_container check handles qualified
+    entries ("Foo.bar"), while self_names handles the container name itself ("Foo")
+    and BARE member entries ("bar", whose owning_container is None).
+
+    Args:
+        entry_name:  the dependent symbol's name (bare or qualified).
+        container:   the target's container, or None when the target is a free
+                     function / bare name with no container. None -> always False
+                     (a target with no container can have no self-references).
+        self_names:  {container} ∪ {bare member names}. Bare members must be listed
+                     explicitly because owning_container("bar") is None.
+
+    Never raises. Returns False on the safe (external) side when container is None.
+    """
+    if not container:
+        return False
+    if entry_name in self_names:
+        return True
+    return owning_container(entry_name) == container
+
+
+def relevance_key(
+    entry: dict[str, Any],
+    container: str | None,
+    self_names: set[str],
+) -> tuple[bool, bool]:
+    """Sort key ordering external-production entries first, self-references last.
+
+    Returns (is_self_ref, is_test). Python sorts False < True, so the ascending
+    order is:
+        (False, False) — external production   ← kept first under the cap
+        (False, True)  — external test
+        (True,  False) — self-ref production
+        (True,  True)  — self-ref test          ← dropped first under the cap
+
+    This SUPERSEDES the prior single-key production-before-test sort by adding
+    self-reference as the PRIMARY key while keeping is_test as the secondary key.
+    Used with a STABLE sort, so the analysis layer's ascending-distance/alphabetical
+    order is preserved within each group and results stay deterministic.
+    """
+    is_self = classify_self_ref(entry.get("name", ""), container, self_names)
+    is_test = bool(entry.get("is_test", False))
+    return (is_self, is_test)
+
+
+def order_by_relevance(
+    entries: list[dict[str, Any]],
+    container: str | None,
+    self_names: set[str],
+) -> list[dict[str, Any]]:
+    """Return entries stably re-ordered external-first, self-references last.
+
+    Stable: within the external and self-reference groups the input order
+    (the analysis layer's ascending-distance/alphabetical order) is preserved,
+    so the closest external dependents survive an entries[:limit] cap.
+    Never mutates the input list.
+    """
+    return sorted(entries, key=lambda e: relevance_key(e, container, self_names))
+
+
+def partition_self_refs(
+    entries: list[dict[str, Any]],
+    container: str | None,
+    self_names: set[str],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Split entries into (external, self_refs), preserving input order in each.
+
+    Used by the "hide" self-ref mode: externals are kept in the output, self_refs
+    are dropped and only their COUNT is surfaced (mirrors the hidden_tests
+    mechanism). Never mutates the input list.
+    """
+    external: list[dict[str, Any]] = []
+    self_refs: list[dict[str, Any]] = []
+    for entry in entries:
+        if classify_self_ref(entry.get("name", ""), container, self_names):
+            self_refs.append(entry)
+        else:
+            external.append(entry)
+    return external, self_refs

seam/analysis/rwr.py

@@ -0,0 +1,129 @@
+"""Pure personalized-PageRank (Random-Walk-with-Restart) module — E3 neighbor ranking.
+
+Public API:
+    personalized_pagerank(adjacency, seeds, *, restart, iters, tol) -> dict[str, float]
+
+This is a DEEP PURE module: graph + seed set in → relevance scores out.
+No SQLite, no file I/O, no config, no side effects (mirrors clustering.py).
+
+`seeds` is a SET because a method symbol stored as "Class.method" can have call edges keyed under
+the bare "method" (Seam's qualified/bare asymmetry). Personalizing the walk over BOTH forms (the
+symbol's edge_match_names) ensures neighbours reachable via either form are scored relative to the
+same logical seed.
+
+WHY RWR for neighbor ranking (vs. raw degree):
+    Ranking a symbol's 1-hop neighbors by how RELEVANT they are TO THAT SYMBOL needs more than
+    degree centrality. RWR restarts the walk at the seed every step with probability `restart`,
+    so mass concentrates on nodes the seed actually reaches and re-reaches. A neighbor woven into
+    the seed's local neighborhood (it shares callers/callees with the seed → same functional
+    cluster) accumulates more score than a globally-popular but topically-distant neighbor. That
+    "closeness to the seed" is exactly what a context bundle wants to keep when it must cap.
+
+Algorithm (power-iterated personalized PageRank):
+    r_{k+1}[n] = restart * teleport[n] + (1 - restart) * Σ_{m: n ∈ adj[m]} r_k[m] / outdeg(m)
+    where teleport is all mass on `seed` (personalization). Dangling/isolated mass (a node with
+    no neighbors) is sent back to the seed so probability is conserved. Undirected adjacency is
+    assumed (the caller symmetrizes), matching CodeGraph's computeGraphRelevance.
+
+Determinism is load-bearing: nodes are processed in sorted order and the math is exact-rational-
+free float arithmetic with a fixed iteration cap, so the same graph always yields the same scores.
+
+Degenerate inputs (never raises):
+    - empty adjacency                          -> {}
+    - no seed present in adjacency             -> {} (cannot personalize → caller skips ranking)
+    - seeds present but isolated (no edges)    -> all mass on the seed set
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Module constants (implementation details, not user-facing knobs):
+# restart 0.15 = the canonical PageRank teleport probability; the exact value is not sensitive
+# for RANKING (only the relative order of scores matters). 30 iterations + 1e-6 L1 tolerance
+# converge comfortably on the bounded subgraphs E3 feeds in (~hundreds of nodes).
+_DEFAULT_RESTART = 0.15
+_DEFAULT_ITERS = 30
+_DEFAULT_TOL = 1e-6
+
+
+def personalized_pagerank(
+    adjacency: dict[str, set[str]],
+    seeds: set[str],
+    *,
+    restart: float = _DEFAULT_RESTART,
+    iters: int = _DEFAULT_ITERS,
+    tol: float = _DEFAULT_TOL,
+) -> dict[str, float]:
+    """Personalized PageRank (RWR) scores for every node, personalized to the `seeds` set.
+
+    Args:
+        adjacency: node name -> set of neighbor names. Assumed UNDIRECTED (caller symmetrizes).
+                   Neighbor names not present as keys are ignored (dangling targets).
+        seeds:     the nodes the walk restarts at (the symbol's edge_match_names — qualified +
+                   bare). Teleport mass is split uniformly across the seeds present in the graph.
+        restart:   teleport-to-seeds probability per step (0 < restart < 1).
+        iters:     max power iterations.
+        tol:       L1-convergence threshold; iteration stops early once the score vector moves
+                   less than this between steps.
+
+    Returns:
+        dict node -> score (scores sum to ~1.0). Higher = more relevant to the seed set.
+        Returns {} when no seed is present in the graph (caller then skips ranking). Never raises.
+    """
+    try:
+        # Restrict to nodes that are keys; drop edges to unknown nodes so out-degree and the
+        # back-distribution stay consistent (mirrors clustering.py's "edges referencing unknown
+        # nodes are safely ignored").
+        nodes = sorted(adjacency.keys())
+        if not nodes:
+            return {}
+        node_set = set(nodes)
+        # Symmetric, self-loop-free neighbor lists restricted to known nodes.
+        nbrs: dict[str, list[str]] = {
+            n: sorted({m for m in adjacency.get(n, ()) if m in node_set and m != n})
+            for n in nodes
+        }
+
+        # Teleport distribution: uniform over the seeds that actually exist in the graph.
+        present_seeds = sorted(s for s in seeds if s in node_set)
+        if not present_seeds:
+            return {}  # cannot personalize → caller falls back to min_id order
+        teleport: dict[str, float] = {n: 0.0 for n in nodes}
+        seed_share = 1.0 / len(present_seeds)
+        for s in present_seeds:
+            teleport[s] = seed_share
+
+        # Start all mass on the seed set (teleport vector).
+        rank: dict[str, float] = dict(teleport)
+        walk = 1.0 - restart
+
+        for _ in range(iters):
+            nxt: dict[str, float] = {n: 0.0 for n in nodes}
+            dangling_mass = 0.0
+            # Push each node's current mass to its neighbors (walk component).
+            for n in nodes:
+                deg = len(nbrs[n])
+                if deg == 0:
+                    # Isolated/dangling node: its walk mass has nowhere to go → redirect to the
+                    # seed set below (conserves total probability instead of leaking it).
+                    dangling_mass += rank[n]
+                    continue
+                share = rank[n] / deg
+                for m in nbrs[n]:
+                    nxt[m] += share
+            # Apply the (1 - restart) walk weight, then add the restart teleport + the dangling
+            # mass, both distributed over the seed set.
+            for n in nodes:
+                nxt[n] = walk * nxt[n] + (restart + walk * dangling_mass) * teleport[n]
+
+            # L1 convergence check.
+            delta = sum(abs(nxt[n] - rank[n]) for n in nodes)
+            rank = nxt
+            if delta < tol:
+                break
+
+        return rank
+    except Exception:  # noqa: BLE001 — pure module must never raise; degrade to no-ranking.
+        logger.debug("personalized_pagerank: degraded for seeds=%r", seeds, exc_info=True)
+        return {}

seam/analysis/staleness.py

@@ -0,0 +1,328 @@
+"""Index staleness detector — single source of truth for "is this index stale".
+
+Given an open DB connection + the project root, returns a StalenessVerdict.
+Encapsulates the "is this index stale" logic behind one clean interface and is
+the single source of truth — `seam status` and the MCP read tools both use it.
+
+Algorithm (bounded-scan + per-process TTL cache):
+  1. Query the N most recently indexed REAL files (path NOT LIKE ':%'), ordered
+     by indexed_at DESC, LIMIT SEAM_STALENESS_SCAN_CAP.
+  2. For each file in that set, compare on-disk st_mtime vs stored mtime.
+     - Newer on-disk mtime → file was modified since last index → stale.
+     - OSError (file missing / permission denied) on a real file path → deleted → stale.
+  3. If the watcher is alive (watcher_alive=True), file drift is NOT reported as
+     stale — the watcher self-heals file changes. HOWEVER, if synthesized edges
+     exist in the DB (SELECT COUNT(*) > 0 WHERE synthesized_by IS NOT NULL), still
+     report stale because the watcher never recomputes synthesized edges or clusters.
+  4. Cache the verdict in a module-level dict keyed by (resolved db_path, resolved root)
+     for SEAM_STALENESS_TTL_SECONDS to avoid re-stat on every MCP read call.
+
+Conservatism direction: on any IO/DB error, return stale=False (do NOT cry wolf).
+WHY: a false-positive stale banner erodes agent trust; a missed staleness is a
+pre-existing condition (agents already lived without the banner).
+
+Never raises. All IO wrapped in try/except. Degrades gracefully on pre-v12 indexes
+(the synthesized_by guard handles the missing-column case).
+
+Mirrors the leaf discipline of seam/analysis/affected.py:
+  - imports only stdlib + seam/config
+  - takes a conn + root (not pure-leaf, but bounded/safe IO only)
+  - never raises, never mutates the DB
+"""
+
+import logging
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import TypedDict
+
+import seam.config as config
+
+logger = logging.getLogger(__name__)
+
+# ── Public types ───────────────────────────────────────────────────────────────
+
+
+class StalenessVerdict(TypedDict):
+    """Result shape returned by check_staleness().
+
+    Fields:
+        stale   — True when the index is believed to be stale; False otherwise.
+                  When False, callers omit the banner entirely (absence = fresh).
+        reason  — Human/agent-readable cause of staleness. Empty string when fresh.
+        hint    — The specific remedy. Empty string when fresh.
+                  File drift → "Run 'seam sync' to reconcile the index."
+                  Synthesized-edge drift → "Run 'seam init' or 'seam sync' ..."
+    """
+
+    stale: bool
+    reason: str
+    hint: str
+
+
+# ── Hints (single source of truth for hint text) ───────────────────────────────
+
+_HINT_FILE_DRIFT = "Run 'seam sync' to reconcile the index."
+_HINT_SYNTH_DRIFT = (
+    "Run 'seam init' or 'seam sync' to refresh synthesized edges and clusters."
+)
+
+# ── Per-process TTL verdict cache ──────────────────────────────────────────────
+
+# Keyed by (db_path_str, root_str) → (cached_at: float, verdict: StalenessVerdict).
+# Module-level dict is safe: one dict per process, bounded by number of unique DB paths
+# (typically 1–2 in any real server process). No eviction needed; TTL guards freshness.
+_cache: dict[str, tuple[float, StalenessVerdict]] = {}
+
+
+def _cache_key(conn: sqlite3.Connection, root: Path) -> str:
+    """Build a string cache key from the DB path and root path."""
+    try:
+        raw_db_path = conn.execute("PRAGMA database_list").fetchone()[2]
+        # Normalize the DB path too (not just root) so two spellings of the same DB
+        # can't produce duplicate cache entries.
+        db_path = str(Path(raw_db_path).resolve()) if raw_db_path else "<unknown>"
+    except Exception:  # noqa: BLE001 — closed/invalid conn → no cache
+        db_path = "<unknown>"
+    return f"{db_path}||{root.resolve()}"
+
+
+def _cache_get(key: str) -> StalenessVerdict | None:
+    """Return a cached verdict if still within TTL, else None."""
+    entry = _cache.get(key)
+    if entry is None:
+        return None
+    cached_at, verdict = entry
+    ttl = config.SEAM_STALENESS_TTL_SECONDS
+    if ttl > 0 and (time.time() - cached_at) < ttl:
+        return verdict
+    # Expired — evict.
+    _cache.pop(key, None)
+    return None
+
+
+def _cache_put(key: str, verdict: StalenessVerdict) -> None:
+    """Store a verdict in the cache."""
+    _cache[key] = (time.time(), verdict)
+
+
+# ── Watcher liveness probe ─────────────────────────────────────────────────────
+
+
+def _watcher_is_alive(pid_file: Path) -> int | None:
+    """Return the PID if a live watcher process is recorded, else None.
+
+    Reads the PID file and probes the process with os.kill(pid, 0). A stale
+    PID file (process gone) returns None so callers can safely overwrite it.
+
+    Extracted here from cli/main.py to be importable by the handler layer
+    without creating a seam.server → seam.cli import cycle.
+    """
+    if not pid_file.exists():
+        return None
+    try:
+        pid = int(pid_file.read_text().strip())
+    except (OSError, ValueError):
+        return None
+    try:
+        os.kill(pid, 0)  # signal 0 = liveness probe, doesn't actually signal
+    except OSError:
+        return None  # no such process (or not ours) — treat as dead
+    return pid
+
+
+# ── Synthesized-edge check ─────────────────────────────────────────────────────
+
+
+def _has_synthesized_edges(conn: sqlite3.Connection) -> bool:
+    """Return True if the DB has any synthesized edges (synthesized_by IS NOT NULL).
+
+    WHY: the watcher never recomputes synthesized edges or clusters. Even with a
+    live watcher, a synthesis-enabled index becomes stale for synthesized data.
+
+    Guard for pre-v12 indexes: if the synthesized_by column doesn't exist, return
+    False (conservatism: treat as no synthesized edges, don't report staleness).
+    """
+    try:
+        row = conn.execute(
+            "SELECT COUNT(*) FROM edges WHERE synthesized_by IS NOT NULL"
+        ).fetchone()
+        return bool(row and row[0] > 0)
+    except Exception:  # noqa: BLE001 — pre-v12 DB (no synthesized_by column), or closed conn
+        return False
+
+
+# ── Core detection ─────────────────────────────────────────────────────────────
+
+
+def _scan_for_drift(
+    conn: sqlite3.Connection,
+    scan_cap: int,
+) -> tuple[int, int]:
+    """Scan the N most recently indexed real files for mtime drift and deletions.
+
+    Returns (changed_count, deleted_count).
+
+    WHY bounded scan: only the newest `scan_cap` files are stat'd. A stale file
+    outside the cap window is NOT detected — this is the documented limitation.
+    On a repo with 10k files, checking all of them on every MCP read call would
+    add ~50-100ms per call on spinning disk.
+    """
+    rows = conn.execute(
+        """
+        SELECT path, mtime
+        FROM files
+        WHERE path NOT LIKE ':%'
+        ORDER BY indexed_at DESC
+        LIMIT ?
+        """,
+        (scan_cap,),
+    ).fetchall()
+
+    changed = 0
+    deleted = 0
+    for row in rows:
+        stored_path, stored_mtime = row[0], row[1]
+        p = Path(stored_path)
+        try:
+            disk_mtime = p.stat().st_mtime
+            if disk_mtime > stored_mtime:
+                changed += 1
+        except OSError:
+            # File is gone (deleted) or permission denied.
+            # Both count as "stale" — the index references something that changed.
+            deleted += 1
+
+    # Observability: when the scan fills the cap, the verdict covers only the newest
+    # `scan_cap` files — a stale file OUTSIDE that window reads identical to a clean
+    # repo. Log it so a "fresh" verdict on a large repo is not silently partial.
+    if len(rows) >= scan_cap:
+        logger.info(
+            "check_staleness: scan hit cap (%d files) — verdict covers only the "
+            "newest %d indexed files; older drift is not detected",
+            scan_cap,
+            scan_cap,
+        )
+    return changed, deleted
+
+
+def check_staleness(
+    conn: sqlite3.Connection,
+    *,
+    root: Path,
+    watcher_alive: bool = False,
+    scan_cap: int | None = None,
+    respect_knob: bool = True,
+) -> StalenessVerdict:
+    """Determine whether the index is stale relative to the current on-disk state.
+
+    Args:
+        conn:          Open SQLite connection (read-only; never mutated).
+        root:          Absolute project root path. Used for cache key and watcher
+                       PID-file location derivation.
+        watcher_alive: When True, the watcher is running and self-heals file drift.
+                       File mtime drift is then NOT reported as stale (but
+                       synthesized-edge drift still is).
+        scan_cap:      Override for SEAM_STALENESS_SCAN_CAP (used by tests to
+                       exercise the boundary without setting the config).
+        respect_knob:  When True (default), SEAM_STALENESS_CHECK=off short-circuits
+                       to a fresh verdict (the MCP-banner gate). The `seam status`
+                       CLI passes respect_knob=False so its freshness field is
+                       computed regardless of the banner knob — the knob gates the
+                       MCP banner, NOT the unrelated CLI freshness feature, which
+                       predates it and must not be silently disabled by it.
+
+    Returns:
+        StalenessVerdict with stale, reason, hint.
+
+    Never raises. On any error, returns stale=False (conservative default; do NOT
+    cry wolf when freshness cannot be determined).
+    """
+    # Banner gate: knob off → no IO, no banner, byte-identical to pre-feature.
+    # The handlers skip calling this when the knob is off; this guard is the safety
+    # net for direct callers. `seam status` opts out (respect_knob=False) so the
+    # CLI freshness field stays live even when the MCP banner is disabled.
+    if respect_knob and config.SEAM_STALENESS_CHECK != "on":
+        return StalenessVerdict(stale=False, reason="", hint="")
+
+    # Resolve scan_cap: test override takes precedence; otherwise use config.
+    effective_cap = scan_cap if scan_cap is not None else config.SEAM_STALENESS_SCAN_CAP
+
+    # Per-process TTL cache: a known-stale verdict is reused within the TTL so a
+    # burst of read-tool calls doesn't re-scan a repo we already know is stale.
+    cache_key = _cache_key(conn, root)
+    cached = _cache_get(cache_key)
+    if cached is not None:
+        logger.debug("check_staleness: returning cached verdict (stale=%s)", cached["stale"])
+        return cached
+
+    try:
+        verdict = _check_staleness_impl(conn, watcher_alive=watcher_alive, scan_cap=effective_cap)
+    except Exception:  # noqa: BLE001 — never propagate to the read-tool caller
+        # Conservative default: stale=False means we don't cry wolf on unexpected errors.
+        # WARNING (not debug): a throw here is genuinely unexpected and silently defeats
+        # a CORRECTNESS feature — an operator must be able to see that the check broke
+        # rather than mistake "check failed" for "verified fresh". The deliberate
+        # no-watcher / no-drift skips stay quiet; only the unexpected path is loud.
+        logger.warning("check_staleness: unexpected error; returning stale=False", exc_info=True)
+        return StalenessVerdict(stale=False, reason="", hint="")
+
+    # Cache ONLY stale verdicts (the safe asymmetry). A fresh verdict is NOT cached:
+    # caching stale=False would mask a file edited within the TTL window — the exact
+    # false-safe this feature exists to prevent (and would also mask a watcher that
+    # died mid-session). Re-verifying a fresh repo is cheap (bounded by scan_cap stats);
+    # persisting a known-stale verdict is the only direction that is safe to cache.
+    if verdict["stale"]:
+        _cache_put(cache_key, verdict)
+    return verdict
+
+
+def _check_staleness_impl(
+    conn: sqlite3.Connection,
+    *,
+    watcher_alive: bool,
+    scan_cap: int,
+) -> StalenessVerdict:
+    """Inner implementation — called from check_staleness under a try/except."""
+    # ── Case 1: watcher is alive ──────────────────────────────────────────────
+    if watcher_alive:
+        # The watcher self-heals file drift in real time, so file-mtime drift is
+        # NOT reported as stale. But synthesized edges / clusters are NEVER
+        # recomputed by the watcher — check for those separately.
+        if _has_synthesized_edges(conn):
+            return StalenessVerdict(
+                stale=True,
+                reason=(
+                    "Synthesized edges and clusters may be stale — "
+                    "the file watcher does not recompute them."
+                ),
+                hint=_HINT_SYNTH_DRIFT,
+            )
+        # File drift is expected (watcher handles it); nothing else to check.
+        return StalenessVerdict(stale=False, reason="", hint="")
+
+    # ── Case 2: no watcher — scan for file drift ──────────────────────────────
+    try:
+        changed, deleted = _scan_for_drift(conn, scan_cap=scan_cap)
+    except Exception:  # noqa: BLE001 — e.g. closed conn; be conservative
+        logger.debug("check_staleness: _scan_for_drift failed; defaulting to stale=False", exc_info=True)
+        return StalenessVerdict(stale=False, reason="", hint="")
+
+    if deleted > 0 and changed > 0:
+        reason = (
+            f"{changed} indexed file(s) changed on disk and "
+            f"{deleted} tracked file(s) were deleted since last index."
+        )
+        return StalenessVerdict(stale=True, reason=reason, hint=_HINT_FILE_DRIFT)
+
+    if deleted > 0:
+        reason = f"{deleted} tracked file(s) were deleted since last index."
+        return StalenessVerdict(stale=True, reason=reason, hint=_HINT_FILE_DRIFT)
+
+    if changed > 0:
+        reason = f"{changed} indexed file(s) changed on disk since last index."
+        return StalenessVerdict(stale=True, reason=reason, hint=_HINT_FILE_DRIFT)
+
+    # No drift found in the scanned window.
+    return StalenessVerdict(stale=False, reason="", hint="")