Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(mcp): hybrid MCP improvements — verified trust contract, honest savings, constant indexing (#467)

Swati Ahuja28f58fb71b39
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd.py b/packages/cli/src/repowise/cli/commands/update_cmd.py
index 2413bbc12..8de56b4b5 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd.py
@@ -396,6 +396,7 @@ def _persist_index_only_update(
head: str | None,
start: float,
changed_paths: list[str],
+ file_diffs: list | None = None,
) -> None:
"""Persist the index-only update (graph + git + dead-code + health), save
state, and print the completion line. No LLM regeneration.
@@ -413,6 +414,7 @@ def _persist_index_only_update(
dead_code_report,
partial_health_report,
changed_paths,
+ file_diffs=file_diffs,
log=console.print,
)
)
@@ -527,9 +529,7 @@ def _run_full_health_rescore(
pass # metrics fall back to lazy computation
exclude_spec = (
- pathspec.PathSpec.from_lines("gitwildmatch", exclude_patterns)
- if exclude_patterns
- else None
+ pathspec.PathSpec.from_lines("gitwildmatch", exclude_patterns) if exclude_patterns else None
)
async def _rescore() -> None:
@@ -555,9 +555,7 @@ def _run_full_health_rescore(
sf = create_session_factory(engine)
async with get_session(sf) as session:
- repo = await upsert_repository(
- session, name=repo_path.name, local_path=str(repo_path)
- )
+ repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))
repo_id = repo.id
gm_result = await session.execute(
@@ -619,9 +617,7 @@ def _run_full_health_rescore(
{**state, "last_sync_commit": head, "config_fingerprint": curr_fingerprint},
)
elapsed = time.monotonic() - start
- console.print(
- f"[green]Config-triggered health re-score complete[/green] in {elapsed:.1f}s"
- )
+ console.print(f"[green]Config-triggered health re-score complete[/green] in {elapsed:.1f}s")
# ---------------------------------------------------------------------------
@@ -923,9 +919,7 @@ def update_command(
# new rules/excludes instead of being left stale.
console.print("[yellow]Config files changed — re-running health analysis.[/yellow]")
if dry_run:
- console.print(
- "[yellow]Dry run — health would be re-scored. No changes made.[/yellow]"
- )
+ console.print("[yellow]Dry run — health would be re-scored. No changes made.[/yellow]")
return
cfg = load_config(repo_path)
exclude_patterns = list(cfg.get("exclude_patterns") or [])
@@ -996,6 +990,7 @@ def update_command(
head,
start,
[fd.path for fd in file_diffs],
+ file_diffs=file_diffs,
)
return
@@ -1025,9 +1020,7 @@ def update_command(
# all subsequent updates.
from repowise.cli.providers import build_cost_tracker
- cost_tracker = build_cost_tracker(
- repo_path, repo_path.name, no_cost_tracking=no_cost_tracking
- )
+ cost_tracker = build_cost_tracker(repo_path, repo_path.name, no_cost_tracking=no_cost_tracking)
provider._cost_tracker = cost_tracker
# (dead_code_report computed above, before the index-only branch)
@@ -1222,6 +1215,17 @@ def update_command(
repo_id = repo.id
for page in generated_pages:
await upsert_page_from_generated(session, page, repo_id)
+ # Tombstone pages for deleted/renamed files — regeneration only
+ # rewrites pages for files that still exist.
+ try:
+ from repowise.core.pipeline.persist import (
+ mark_tombstone_pages,
+ tombstone_candidates,
+ )
+
+ await mark_tombstone_pages(session, repo_id, tombstone_candidates(file_diffs))
+ except Exception as exc:
+ console.print(f"[yellow]Tombstone marking skipped: {exc}[/yellow]")
# Persist updated git metadata + recompute percentiles
if git_meta_map:
diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2
index 7bbac88d2..3f919b7ee 100644
--- a/packages/core/src/repowise/core/generation/templates/claude_md.j2
+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2
@@ -105,22 +105,27 @@ This repo has the Repowise MCP server configured. The tools below answer questio
| Tool | What only this tool answers |
|------|------------------------------|
-| `get_answer(question)` | Synthesised answer with verified citations and a calibrated `retrieval_quality`. First call for "how does X work" / "why is Y like this". On low confidence returns `best_guesses` with one-line justifications instead of an empty answer. |
-| `get_context(targets=[...])` | Triage card for files/modules/symbols — title, summary, signatures, `hotspot` bit, `decision_records` titles, and `symbol_id`s to pipe into `get_symbol`. Use `include=["callers","ownership",...]` to widen. NOT for source bytes. |
-| `get_symbol("path/to/file.py::Name")` | Raw source bytes for one indexed symbol with exact line bounds. Cheaper and safer than `Read` + offset math. Use the `symbol_id` returned by `get_context`. |
-| `search_codebase(query, kind?)` | Find pages by concept when you don't know the file. Each result carries `search_method` (`embedding` vs `bm25` fallback). For exact identifiers use Grep — the tool will hint when it sees one. |
+| `get_answer(question)` | Synthesised answer with citations and a content-grounded `confidence`. First call for "how does X work" / "where is Y" / "why is Z". Value questions may return `grounding: "extracted"` — the verbatim source line, no synthesis involved. On low confidence returns `best_guesses` with one-line justifications. |
+| `get_context(targets=[...])` | Triage card for files/modules/symbols — title, summary, signatures, `hotspot` bit, `decision_records` titles, `symbol_id`s. File targets auto-upgrade to a `verified` skeleton (every signature, ~37% of a full Read). `include=["callers"]` works on file targets too (import + call rollup). |
+| `get_symbol(...)` | Source bytes with live-verified bounds. Three forms: `"path.py::Name"` (indexed symbol), `"path.py:140-180"` (live range read, ≤200 lines), `"repowise#<hex>"` (omission ref). Index misses return `fallback_lines` from a live grep instead of a dead end. |
+| `search_codebase(query, kind?)` | Find pages by concept when you don't know the file. Results carry `search_method` (`embedding` vs `bm25` fallback). Decision records rank below file pages unless the query is why-shaped. Identifier-bearing queries get a `grep_hint` — prefer Grep for those tokens. |
| `get_why(query, targets?)` | Architectural decision archaeology — *why* the code is shaped this way. Call before refactors or pattern divergences. Falls back to git archaeology when no ADRs exist for a file. |
| `get_risk(targets, changed_files?)` | What history says about touching these files: churn, owners, blast radius. Pass `changed_files` for PR mode → returns a `directive` (`will_break`, `missing_cochanges`, `missing_tests`). |
| `get_dead_code(...)` | Tiered unreachable / unused-export / zombie-package findings. Run before a cleanup sprint, not before a targeted fix. |
-| `get_overview(repo?)` | Architecture map for an unfamiliar repo. One-time orientation; skip on subsequent calls in the same session. |
+| `get_overview(repo?)` | Architecture map + `tool_guide` recipes. One-time orientation; skip on subsequent calls in the same session. |
+
+**Trust protocol — when a response replaces reading the source:**
+- `verified: true` on any response means the served content was checked against the live working tree. **Never follow a verified response with a Read of the same lines** — you would be paying twice for identical bytes.
+- `get_answer` with `confidence: "high"` or `grounding: "extracted"` is content-grounded (asserted values were verified against retrieved source; ≥1 citation is source-backed). Cite it directly. `quotes` entries `{path, lines, quote}` are verbatim live source — quote them instead of re-reading.
+- Reading code: `get_context` skeleton first (~37% of a full Read), then `get_symbol` for bodies, `"path.py:a-b"` range reads for anything between symbols. Raw `Read` is for files the index marks `mostly_full` or cannot serve.
+- The **only** re-read triggers: `bounds: "approximate"`, `_meta.stale_warning`, `search_method: "bm25"`, or `confidence: "low"`/`retrieval_quality: "weak"`.
+- Disallowed rationalizations for extra reads: "just to be safe", "to double-check the tool", "to see the full context" (use the skeleton / a range read), "the file might have changed" (that is what `verified` already checked).
**Composition tips:**
-- `get_answer` → if `confidence` is `medium`/`low`, follow the `best_guesses[0].file` or `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.
-- `get_context` returns `decision_records` titles → call `get_why(targets=[...])` for the rationale.
-- `get_context` returns `hotspot: true` → call `get_risk` before editing.
+- `get_answer` → if `confidence` is `medium`/`low`, follow `best_guesses[0].file` or `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.
+- `get_context` returns `decision_records` titles → `get_why(targets=[...])` for the rationale; `hotspot: true` → `get_risk` before editing.
- PR review → `get_risk(targets=[...], changed_files=[...])`; read the `directive` block first.
-
-**Verify when:** `_meta.stale_warning` is present, or `retrieval_quality` is `partial`/`weak`, or `search_method` is `bm25`. Otherwise trust the response and act on it.
+- A `tombstone` error means the file was deleted/renamed since indexing — follow `successor_paths`.
### Output Distillation
diff --git a/packages/core/src/repowise/core/ingestion/extractors/signatures.py b/packages/core/src/repowise/core/ingestion/extractors/signatures.py
index 6f2c542af..9060cea43 100644
--- a/packages/core/src/repowise/core/ingestion/extractors/signatures.py
+++ b/packages/core/src/repowise/core/ingestion/extractors/signatures.py
@@ -58,5 +58,15 @@ def build_signature(node_type: str, name: str, params_text: str, def_node: Node,
return f"impl {name}"
if node_type in ("class_specifier",):
return f"class {name}"
+ if node_type in ("assignment", "variable_declarator"):
+ # Module-level constant/variable: the signature IS the assignment —
+ # the verbatim line answers "what is the default value of X" without
+ # a follow-up source read. First line only, bounded; multi-line
+ # values (dicts, arrays) stay reachable via get_symbol.
+ text = node_text(def_node, src)
+ first_line = text.splitlines()[0].strip() if text else name
+ if len(first_line) > 160:
+ first_line = first_line[:157] + "..."
+ return first_line
# Fallback
return f"{name}{params_text}"
diff --git a/packages/core/src/repowise/core/ingestion/language_configs.py b/packages/core/src/repowise/core/ingestion/language_configs.py
index 0f0065919..c708c964a 100644
--- a/packages/core/src/repowise/core/ingestion/language_configs.py
+++ b/packages/core/src/repowise/core/ingestion/language_configs.py
@@ -58,12 +58,14 @@ class LanguageConfig:
parent_class_types: frozenset[str] = field(default_factory=frozenset)
-
LANGUAGE_CONFIGS: dict[str, LanguageConfig] = {
"python": LanguageConfig(
symbol_node_types={
"function_definition": "function",
"class_definition": "class",
+ # Module-level assignments (the .scm pattern is module-anchored).
+ # Refined in the parser: SCREAMING_CASE → constant, else variable.
+ "assignment": "constant",
},
import_node_types=["import_statement", "import_from_statement"],
export_node_types=[],
@@ -83,6 +85,9 @@ LANGUAGE_CONFIGS: dict[str, LanguageConfig] = {
"enum_declaration": "enum",
"method_definition": "method",
"lexical_declaration": "function", # const foo = () => {}
+ # Top-level const/let with a literal value (the .scm pattern is
+ # program-anchored). Refined in the parser like Python assignments.
+ "variable_declarator": "constant",
},
import_node_types=["import_statement"],
export_node_types=["export_statement"],
@@ -98,6 +103,7 @@ LANGUAGE_CONFIGS: dict[str, LanguageConfig] = {
"class_declaration": "class",
"method_definition": "method",
"lexical_declaration": "function",
+ "variable_declarator": "constant",
},
import_node_types=["import_statement"],
export_node_types=["export_statement"],
diff --git a/packages/core/src/repowise/core/ingestion/parser.py b/packages/core/src/repowise/core/ingestion/parser.py
index 71aa5c002..00ee0c6e8 100644
--- a/packages/core/src/repowise/core/ingestion/parser.py
+++ b/packages/core/src/repowise/core/ingestion/parser.py
@@ -80,6 +80,12 @@ _SYMBOL_COUNT_WARN_THRESHOLD = 500
QUERIES_DIR = Path(__file__).parent / "queries"
+# Node types whose .scm patterns are anchored at module/program level
+# (constants and module variables). They can never be function-local, so
+# the callable-ancestor filter must not apply — and for TS/JS declarators
+# it would misfire on the parent lexical_declaration kind mapping.
+_MODULE_ANCHORED_NODE_TYPES = frozenset({"assignment", "variable_declarator"})
+
@lru_cache(maxsize=None)
def _load_compiled_query(lang: str, grammar_tag: str | None = None) -> object | None:
@@ -363,8 +369,13 @@ class ASTParser:
# exports. Filtering by callable ancestor restricts extraction
# to module-top-level + class-body members. Class bodies don't
# match (``class_definition`` is not callable), so methods are
- # preserved.
- if _has_callable_ancestor(def_node, config.symbol_node_types):
+ # preserved. Module-anchored node types skip the check: their
+ # .scm patterns only match at module/program level, and a TS
+ # variable_declarator's parent (lexical_declaration → "function")
+ # would otherwise read as a callable ancestor.
+ if node_type not in _MODULE_ANCHORED_NODE_TYPES and _has_callable_ancestor(
+ def_node, config.symbol_node_types
+ ):
continue
# Refine "struct" kind for Go type_spec (check if struct or interface body)
@@ -379,6 +390,15 @@ class ASTParser:
):
kind = refine_kotlin_class_kind(def_node)
+ # Refine module-level assignments: SCREAMING_CASE names are
+ # constants by convention; the rest are module variables
+ # (singletons like ``app = FastAPI()``, registries, caches).
+ # ``str.isupper()`` requires at least one cased char, so names
+ # with no letters (``_``, ``__all__``) fall to "variable" rather
+ # than being mislabelled constants by ``name == name.upper()``.
+ if node_type in _MODULE_ANCHORED_NODE_TYPES:
+ kind = "constant" if name.isupper() else "variable"
+
# Params signature text
params_text = _node_text(params_nodes[0], src) if params_nodes else ""
@@ -628,7 +648,8 @@ class ASTParser:
# Language-specific import name + binding extraction
imported_names, bindings = extract_import_bindings(stmt_node, src, file_info.language)
is_relative = (
- module_text.startswith(".") or module_text.startswith("./")
+ module_text.startswith(".")
+ or module_text.startswith("./")
or module_text.startswith(("self::", "super::", "crate::"))
)
diff --git a/packages/core/src/repowise/core/ingestion/queries/javascript.scm b/packages/core/src/repowise/core/ingestion/queries/javascript.scm
index 227eeb458..15371b4e0 100644
--- a/packages/core/src/repowise/core/ingestion/queries/javascript.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/javascript.scm
@@ -36,6 +36,40 @@
)
) @symbol.def
+; Top-level const/let with a non-function value — module constants. The
+; declarator (not the lexical_declaration) is @symbol.def so the kind map
+; can distinguish it from the arrow-function pattern above. Anchored at
+; (program …) — directly or under an export_statement — so function-local
+; declarations never match. require() declarators (call_expression or
+; member_expression values) are imports, never symbols.
+(program
+ (lexical_declaration
+ (variable_declarator
+ name: (identifier) @symbol.name
+ value: [
+ (string) (template_string) (number) (true) (false) (null) (undefined)
+ (array) (object) (unary_expression) (binary_expression)
+ (new_expression)
+ ]
+ ) @symbol.def
+ )
+)
+
+(program
+ (export_statement
+ (lexical_declaration
+ (variable_declarator
+ name: (identifier) @symbol.name
+ value: [
+ (string) (template_string) (number) (true) (false) (null) (undefined)
+ (array) (object) (unary_expression) (binary_expression)
+ (new_expression)
+ ]
+ ) @symbol.def
+ )
+ )
+)
+
; ---------------------------------------------------------------------------
; Imports
; ---------------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/ingestion/queries/python.scm b/packages/core/src/repowise/core/ingestion/queries/python.scm
index 394948561..4cfb284b6 100644
--- a/packages/core/src/repowise/core/ingestion/queries/python.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/python.scm
@@ -27,6 +27,17 @@
name: (identifier) @symbol.name
) @symbol.def
+; Module-level assignment — constants and module config values. Anchored at
+; (module …) so function-local and class-body assignments never match; the
+; parser refines the kind (SCREAMING_CASE → constant, otherwise variable).
+(module
+ (expression_statement
+ (assignment
+ left: (identifier) @symbol.name
+ ) @symbol.def
+ )
+)
+
; Decorated function or class — captures the decorator as a modifier
(decorated_definition
(decorator) @symbol.modifiers
diff --git a/packages/core/src/repowise/core/ingestion/queries/typescript.scm b/packages/core/src/repowise/core/ingestion/queries/typescript.scm
index c62fc71ba..cd330d638 100644
--- a/packages/core/src/repowise/core/ingestion/queries/typescript.scm
+++ b/packages/core/src/repowise/core/ingestion/queries/typescript.scm
@@ -66,6 +66,39 @@
name: (property_identifier) @symbol.name
) @symbol.def
+; Top-level const/let with a non-function value — module constants. The
+; declarator (not the lexical_declaration) is @symbol.def so the kind map
+; can distinguish it from the arrow-function pattern above. Anchored at
+; (program …) — directly or under an export_statement — so function-local
+; declarations never match.
+(program
+ (lexical_declaration
+ (variable_declarator
+ name: (identifier) @symbol.name
+ value: [
+ (string) (template_string) (number) (true) (false) (null) (undefined)
+ (array) (object) (unary_expression) (binary_expression)
+ (new_expression) (member_expression) (as_expression) (satisfies_expression)
+ ]
+ ) @symbol.def
+ )
+)
+
+(program
+ (export_statement
+ (lexical_declaration
+ (variable_declarator
+ name: (identifier) @symbol.name
+ value: [
+ (string) (template_string) (number) (true) (false) (null) (undefined)
+ (array) (object) (unary_expression) (binary_expression)
+ (new_expression) (member_expression) (as_expression) (satisfies_expression)
+ ]
+ ) @symbol.def
+ )
+ )
+)
+
; ---------------------------------------------------------------------------
; Imports
; ---------------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index 344965535..af385d126 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -393,6 +393,7 @@ async def persist_incremental_index(
partial_health_report: Any,
changed_paths: list[str],
*,
+ file_diffs: list[Any] | None = None,
log: LogFn | None = None,
) -> None:
"""Persist an incremental index refresh (graph + git + dead-code + health).
@@ -422,6 +423,20 @@ async def persist_incremental_index(
repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))
repo_id = repo.id
+ # Tombstone pages for deleted/renamed files FIRST — a fresh page
+ # for a file that no longer exists misleads every retrieval
+ # consumer until the next full regeneration.
+ if file_diffs:
+ try:
+ from repowise.core.pipeline.persist import (
+ mark_tombstone_pages,
+ tombstone_candidates,
+ )
+
+ await mark_tombstone_pages(session, repo_id, tombstone_candidates(file_diffs))
+ except Exception as exc:
+ log(f"[yellow]Tombstone marking skipped: {exc}[/yellow]")
+
if git_meta_map:
try:
from repowise.core.persistence.crud import (
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index c5f0ee8ff..699c30160 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -15,6 +15,71 @@ import structlog
logger = structlog.get_logger(__name__)
+def tombstone_candidates(file_diffs: list[Any]) -> list[tuple[str, list[str]]]:
+ """(dead_path, successor_paths) pairs from deleted/renamed file diffs.
+
+ A renamed file's old path gets its new path as the successor; a deleted
+ file has no successor. Diffs of other statuses contribute nothing.
+ """
+ out: list[tuple[str, list[str]]] = []
+ for fd in file_diffs or []:
+ status = getattr(fd, "status", None)
+ if status == "deleted" and fd.path:
+ out.append((fd.path, []))
+ elif status == "renamed" and fd.old_path:
+ out.append((fd.old_path, [fd.path] if fd.path else []))
+ return out
+
+
+async def mark_tombstone_pages(
+ session: Any, repo_id: str, candidates: list[tuple[str, list[str]]]
+) -> int:
+ """Mark file pages for deleted/renamed files as tombstones.
+
+ A ``freshness_status="fresh"`` page for a file that no longer exists is
+ an active trap: retrieval serves it, agents cite it, and the index-age
+ metadata says nothing is wrong. Tombstoned pages keep their content
+ (the prose may still orient a reader) but carry status=tombstone and
+ ``successor_paths`` in metadata so serving layers can skip or redirect.
+
+ Returns the number of pages marked.
+ """
+ if not candidates:
+ return 0
+ from sqlalchemy import select
+
+ from repowise.core.persistence.models import Page
+
+ page_ids = {f"file_page:{path}": (path, successors) for path, successors in candidates}
+ res = await session.execute(
+ select(Page).where(Page.repository_id == repo_id, Page.id.in_(page_ids))
+ )
+ marked = 0
+ for page in res.scalars().all():
+ _, successors = page_ids[page.id]
+ page.freshness_status = "tombstone"
+ try:
+ meta = json.loads(page.metadata_json or "{}")
+ except (json.JSONDecodeError, TypeError):
+ meta = {}
+ meta["successor_paths"] = successors
+ page.metadata_json = json.dumps(meta)
+ marked += 1
+ if marked:
+ logger.info("pages_tombstoned", repo_id=repo_id, count=marked)
+ elif candidates:
+ # Candidates existed but no page matched — the id scheme drifted from
+ # ``file_page:{path}`` or the paths don't line up. Silent success here
+ # would let stale pages keep serving, so surface it.
+ logger.debug(
+ "tombstone_no_match",
+ repo_id=repo_id,
+ candidate_count=len(candidates),
+ sample=[p for p, _ in candidates[:3]],
+ )
+ return marked
+
+
async def persist_graph_nodes(
session: Any,
repo_id: str,
diff --git a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
index 6ae453f54..bbf65ee15 100644
--- a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
+++ b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
@@ -192,15 +192,16 @@ async def hydrate_hits(hits: list[dict], ctx: Any, *, scope: str | None = None)
page_ids = [h["page_id"] for h in hits]
async with get_session(ctx.session_factory) as session:
res = await session.execute(
- select(Page.id, Page.target_path, Page.summary, Page.page_type).where(
- Page.id.in_(page_ids)
- )
+ select(
+ Page.id, Page.target_path, Page.summary, Page.page_type, Page.freshness_status
+ ).where(Page.id.in_(page_ids))
)
meta_by_id = {
row[0]: {
"target_path": row[1] or "",
"summary": row[2] or "",
"page_type": row[3] or "",
+ "freshness": row[4] or "",
}
for row in res.all()
}
@@ -208,6 +209,10 @@ async def hydrate_hits(hits: list[dict], ctx: Any, *, scope: str | None = None)
out: list[dict] = []
for h in hits:
meta = meta_by_id.get(h["page_id"], {})
+ # Tombstoned pages document deleted/renamed files — serving them as
+ # answer material would cite code that no longer exists.
+ if meta.get("freshness") == "tombstone":
+ continue
target_path = meta.get("target_path", "")
if scope and target_path and not target_path.startswith(scope):
continue
@@ -288,9 +293,7 @@ async def expand_via_graph(hits: list[dict], ctx: Any) -> list[dict]:
"""
if not hits:
return hits
- seed_paths = [
- h.get("target_path") for h in hits[:_GRAPH_EXPAND_TOP_N] if h.get("target_path")
- ]
+ seed_paths = [h.get("target_path") for h in hits[:_GRAPH_EXPAND_TOP_N] if h.get("target_path")]
if not seed_paths:
return hits
existing = {h.get("target_path") for h in hits}
@@ -349,18 +352,20 @@ async def expand_via_graph(hits: list[dict], ctx: Any) -> list[dict]:
parent_score = max((h.get("score", 0.0) for h in hits[:_GRAPH_EXPAND_TOP_N]), default=0.0)
candidates: list[dict] = []
for path, summary, page_type in page_rows:
- candidates.append({
- "page_id": f"file_page:{path}",
- "target_path": path,
- "title": f"File: {path}",
- "summary": summary or "",
- "snippet": (summary or "")[:200],
- "page_type": page_type or "file_page",
- "score": parent_score * _GRAPH_EXPAND_DAMPING,
- "_sources": {"graph_expand"},
- "_expanded_from": "graph",
- "_pagerank": pr_by_path.get(path, 0.0),
- })
+ candidates.append(
+ {
+ "page_id": f"file_page:{path}",
+ "target_path": path,
+ "title": f"File: {path}",
+ "summary": summary or "",
+ "snippet": (summary or "")[:200],
+ "page_type": page_type or "file_page",
+ "score": parent_score * _GRAPH_EXPAND_DAMPING,
+ "_sources": {"graph_expand"},
+ "_expanded_from": "graph",
+ "_pagerank": pr_by_path.get(path, 0.0),
+ }
+ )
# Rank candidates by PageRank within the expansion set so we pick the
# most central neighbor first when we have multiple plausible ones.
diff --git a/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py b/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py
index 58efa925c..e9431257c 100644
--- a/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py
+++ b/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py
@@ -62,18 +62,63 @@ def _estimate_search_codebase(result: dict[str, Any]) -> int:
results = result.get("results")
if not isinstance(results, list):
return 0
+ paths = {r["target_path"] for r in results if isinstance(r, dict) and r.get("target_path")}
+ return len(paths) * SEARCH_FLOOR_PER_HIT
+
+
+#: get_answer subsumes a search_codebase call plus opening the cited files.
+#: Same undersell philosophy as SEARCH_FLOOR_PER_HIT — the dict carries paths,
+#: never sizes.
+ANSWER_SEARCH_FLOOR = 400
+ANSWER_READ_FLOOR_PER_FILE = 400
+
+#: Modest fixed counterfactuals for the analysis tools. Each replaces an
+#: exploration the agent cannot cheaply reproduce (git log/blame spelunking,
+#: ADR archaeology, README + entry-point skim) but whose size the result dict
+#: cannot ground — so a flat, deliberately-low floor per successful call.
+RISK_FLOOR = 500
+WHY_FLOOR = 400
+HEALTH_FLOOR = 400
+OVERVIEW_FLOOR = 1200
+
+
+def _estimate_get_answer(result: dict[str, Any]) -> int:
+ """Search call + cited-file reads the answer obviated.
+
+ Counts only answered calls (non-empty ``answer``): a gated/low response
+ explicitly tells the agent to go read, so the reads still happen and
+ claiming them as saved would repeat the E11 miscalibration.
+ """
+ if not str(result.get("answer") or "").strip():
+ return 0
paths = {
- r["target_path"]
- for r in results
- if isinstance(r, dict) and r.get("target_path")
+ p
+ for p in [*(result.get("citations") or []), *(result.get("fallback_targets") or [])[:3]]
+ if isinstance(p, str) and p
}
- return len(paths) * SEARCH_FLOOR_PER_HIT
+ if not paths:
+ return 0
+ return ANSWER_SEARCH_FLOOR + len(paths) * ANSWER_READ_FLOOR_PER_FILE
+
+
+def _fixed_floor(tokens: int) -> Callable[[dict[str, Any]], int]:
+ """Flat counterfactual for successful calls; errors contribute nothing."""
+
+ def _estimate(result: dict[str, Any]) -> int:
+ return 0 if result.get("error") else tokens
+
+ return _estimate
#: Tool name → estimator. Tools absent here emit no counterfactual (skip).
_ESTIMATORS: dict[str, Callable[[dict[str, Any]], int]] = {
"get_context": _estimate_get_context,
"search_codebase": _estimate_search_codebase,
+ "get_answer": _estimate_get_answer,
+ "get_risk": _fixed_floor(RISK_FLOOR),
+ "get_why": _fixed_floor(WHY_FLOOR),
+ "get_health": _fixed_floor(HEALTH_FLOOR),
+ "get_overview": _fixed_floor(OVERVIEW_FLOOR),
}
diff --git a/packages/server/src/repowise/server/mcp_server/_savings/recorder.py b/packages/server/src/repowise/server/mcp_server/_savings/recorder.py
index 4392ea7c3..3292d269d 100644
--- a/packages/server/src/repowise/server/mcp_server/_savings/recorder.py
+++ b/packages/server/src/repowise/server/mcp_server/_savings/recorder.py
@@ -48,6 +48,34 @@ def record_mcp_saving(
"""
if replaced_tokens <= delivered_tokens or not repo_root:
return False
+ return _write_row(repo_root, tool, f"mcp:{tool}", replaced_tokens, delivered_tokens)
+
+
+def record_mcp_dead_end(
+ repo_root: str | Path | None,
+ tool: str,
+ delivered_tokens: int,
+) -> bool:
+ """Debit a dead-end call: tokens delivered, nothing replaced.
+
+ An error response costs the agent its full delivered size and saves
+ nothing. Recording raw=0 / distilled=delivered makes the row a negative
+ contribution at aggregation (saved = raw - distilled) — without these
+ debits the ledger only ever credits and overstates net savings (the E11
+ sign-flip: +138.7k claimed while the session net-spent).
+ """
+ if delivered_tokens <= 0 or not repo_root:
+ return False
+ return _write_row(repo_root, tool, f"mcp:{tool}:dead_end", 0, delivered_tokens)
+
+
+def _write_row(
+ repo_root: str | Path,
+ tool: str,
+ source: str,
+ raw_tokens: int,
+ distilled_tokens: int,
+) -> bool:
db_path = Path(repo_root) / ".repowise" / OMISSIONS_DIRNAME / OMISSIONS_DB_FILENAME
if not db_path.is_file():
# No repo-local sidecar → repo never opted in via `repowise init`.
@@ -60,10 +88,10 @@ def record_mcp_saving(
try:
store.record_saving(
filter_name=tool,
- source=f"mcp:{tool}",
+ source=source,
command=None,
- raw_tokens=replaced_tokens,
- distilled_tokens=delivered_tokens,
+ raw_tokens=raw_tokens,
+ distilled_tokens=distilled_tokens,
)
return True
except Exception:
diff --git a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py
index c1742649e..6f75ee96c 100644
--- a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py
+++ b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py
@@ -37,7 +37,7 @@ from typing import Any
from repowise.core.distill.budget import estimate_tokens
from . import counterfactual
-from .recorder import record_mcp_saving
+from .recorder import record_mcp_dead_end, record_mcp_saving
logger = logging.getLogger(__name__)
@@ -85,8 +85,18 @@ def _delivered_tokens(result: Any) -> int:
def _record(tool: str, result: Any) -> None:
"""Measure, derive the counterfactual, and record — all best-effort."""
declared = _declared_tokens(result)
- replaced = declared if declared is not None else counterfactual.replaced_tokens_for(tool, result)
+ replaced = (
+ declared if declared is not None else counterfactual.replaced_tokens_for(tool, result)
+ )
if replaced <= 0:
+ # Dead-end debit: an error response delivered tokens and replaced
+ # nothing — net negative for the session, and the ledger must say so.
+ if isinstance(result, dict) and result.get("error"):
+ from repowise.server.mcp_server import _state
+
+ record_mcp_dead_end(
+ getattr(_state, "_repo_path", None), tool, _delivered_tokens(result)
+ )
return
delivered = _delivered_tokens(result)
diff --git a/packages/server/src/repowise/server/mcp_server/_verify.py b/packages/server/src/repowise/server/mcp_server/_verify.py
new file mode 100644
index 000000000..0aaa1944f
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/_verify.py
@@ -0,0 +1,209 @@
+"""Serve-time freshness verification for symbol bounds.
+
+WikiSymbol line bounds are written at index time and the source file may
+have changed since — historically get_symbol sliced the live file with
+stale bounds and served the wrong lines while ``_meta`` claimed the index
+was fresh. The agent's rational response was to re-read every MCP response
+from disk, which is the verification tax this module deletes.
+
+The contract:
+
+* ``verified: true`` — the served bytes were checked against the live
+ file (either the stored bounds still match, or the file was re-parsed
+ and the bounds corrected). A verified response never needs a follow-up
+ Read.
+* ``bounds: "approximate"`` — the live file no longer contains the symbol
+ where the index said (rename/delete since indexing) and re-location
+ failed; the served slice is the indexed guess, treat accordingly.
+
+Verification is two-tier:
+
+1. Cheap gate (every call): the symbol's bare name must appear on its
+ stored definition line in the live file. String containment on one
+ line — effectively free since the file is already read for slicing.
+2. Re-parse (mismatch only): tree-sitter re-parses just this file
+ (compiled queries are process-cached; milliseconds), the symbol is
+ re-located by id → (name, parent) → name, and the corrected bounds are
+ written back to the WikiSymbol row so the next call hits the cheap
+ gate again.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+
+from repowise.core.persistence.models import WikiSymbol
+
+_log = logging.getLogger("repowise.mcp.verify")
+
+# Substring containment on a 1-2 char name is meaningless — a constant named
+# ``T`` (TypeVar) or ``e`` "matches" almost any line. Names shorter than this
+# skip the cheap gate and go straight to a re-parse, which can actually
+# confirm them. (Module-level constants/variables now indexed make short
+# names common, so the gate must not rubber-stamp them.)
+_MIN_GATE_NAME_LEN = 3
+
+
+@dataclass
+class BoundsCheck:
+ """Outcome of verifying one symbol's bounds against live source."""
+
+ start_line: int
+ end_line: int
+ verified: bool
+ corrected: bool = False # True when re-parse moved the bounds
+ approximate: bool = False # True when the symbol could not be re-located
+
+
+def name_at_line(lines: list[str], name: str, start_line: int) -> bool:
+ """Cheap gate: does the stored definition line still carry the name?
+
+ ``lines`` is the live file split into lines; ``start_line`` is
+ 1-indexed. The bare name (last segment of a qualified name) must appear
+ as a substring of the definition line — true for def/class/assignment
+ lines across every indexed language.
+ """
+ if start_line < 1 or start_line > len(lines):
+ return False
+ bare = _bare_name(name)
+ return bool(bare) and bare in lines[start_line - 1]
+
+
+def _bare_name(name: str) -> str:
+ """Last segment of a qualified name, regardless of separator style."""
+ return (name or "").rsplit(".", 1)[-1].rsplit("::", 1)[-1]
+
+
+def _line_indent(line: str) -> int:
+ return len(line) - len(line.lstrip())
+
+
+def end_anchor_holds(lines: list[str], start_line: int, end_line: int) -> bool:
+ """Cheap end check: the line past the stored end isn't still the body.
+
+ The start gate confirms the definition line, but it cannot see an edit
+ *inside* the body — lines inserted after the definition leave the def
+ line in place while pushing the true end down, so the stored end now
+ truncates the symbol. We can't pin the exact end without re-parsing, but
+ we can catch that common failure cheaply: if the line immediately after
+ the stored end is indented deeper than the definition line, the body
+ grew and the stored end is wrong. EOF, a blank line, or a dedented line
+ is consistent with a real boundary (brace-closers and module-level
+ neighbours both satisfy ``<=`` the definition indent).
+ """
+ if end_line < start_line or end_line < 1 or end_line > len(lines):
+ return False
+ def_indent = _line_indent(lines[start_line - 1])
+ if end_line >= len(lines):
+ return True # symbol ends at EOF
+ after = lines[end_line] # 0-indexed: first line past the 1-indexed end
+ if not after.strip():
+ return True
+ return _line_indent(after) <= def_indent
+
+
+def relocate_symbol(row: WikiSymbol, source_text: str) -> tuple[int, int] | None:
+ """Re-parse the live file and find the symbol's current bounds.
+
+ Returns (start_line, end_line) or None when the symbol no longer
+ exists in the file (deleted/renamed) or the file cannot be parsed.
+ """
+ try:
+ from repowise.core.ingestion.models import FileInfo
+ from repowise.core.ingestion.parser import ASTParser
+
+ fi = FileInfo(
+ path=row.file_path,
+ abs_path=row.file_path,
+ language=row.language,
+ size_bytes=len(source_text),
+ git_hash="",
+ last_modified=datetime.now(),
+ is_test=False,
+ is_config=False,
+ is_api_contract=False,
+ is_entry_point=False,
+ )
+ parsed = ASTParser().parse_file(fi, source_text.encode("utf-8", errors="replace"))
+ except Exception as exc:
+ _log.warning("re-parse failed for %s: %s", row.file_path, exc)
+ return None
+
+ symbols = parsed.symbols or []
+ # Strongest match first: exact symbol_id, then (name, parent), then name.
+ for sym in symbols:
+ if sym.id == row.symbol_id:
+ return sym.start_line, sym.end_line
+ for sym in symbols:
+ if sym.name == row.name and (sym.parent_name or None) == (row.parent_name or None):
+ return sym.start_line, sym.end_line
+ candidates = [s for s in symbols if s.name == row.name]
+ if len(candidates) == 1:
+ return candidates[0].start_line, candidates[0].end_line
+ return None
+
+
+def check_symbol_bounds(row: WikiSymbol, source_text: str) -> BoundsCheck:
+ """Verify (and if needed correct) a symbol's bounds against live source.
+
+ Cheap gate (no re-parse) only when ALL hold: the name is long enough for
+ substring containment to mean something, it still sits on the stored
+ definition line, AND the stored end still bounds the body. Any miss
+ falls through to a one-file re-parse that pins the true bounds.
+ """
+ lines = source_text.splitlines()
+ bare = _bare_name(row.name)
+ cheap_ok = (
+ len(bare) >= _MIN_GATE_NAME_LEN
+ and name_at_line(lines, row.name, row.start_line)
+ and end_anchor_holds(lines, row.start_line, row.end_line)
+ )
+ if cheap_ok:
+ end = min(max(row.end_line, row.start_line), len(lines))
+ return BoundsCheck(start_line=row.start_line, end_line=end, verified=True)
+
+ located = relocate_symbol(row, source_text)
+ if located is not None:
+ corrected = located != (row.start_line, row.end_line)
+ if corrected:
+ _log.info(
+ "bounds corrected for %s: %d-%d -> %d-%d",
+ row.symbol_id,
+ row.start_line,
+ row.end_line,
+ located[0],
+ located[1],
+ )
+ return BoundsCheck(
+ start_line=located[0], end_line=located[1], verified=True, corrected=corrected
+ )
+
+ return BoundsCheck(
+ start_line=row.start_line,
+ end_line=row.end_line,
+ verified=False,
+ approximate=True,
+ )
+
+
+async def heal_symbol_row(session_factory, row: WikiSymbol, start: int, end: int) -> None:
+ """Persist corrected bounds so the next serve hits the cheap gate.
+
+ Best-effort: a failed heal only costs a re-parse on the next call.
+ """
+ from sqlalchemy import update
+
+ from repowise.core.persistence.database import get_session
+
+ try:
+ async with get_session(session_factory) as session:
+ await session.execute(
+ update(WikiSymbol)
+ .where(WikiSymbol.id == row.id)
+ .values(start_line=start, end_line=end)
+ )
+ await session.commit()
+ except Exception as exc:
+ _log.warning("bounds self-heal failed for %s: %s", row.symbol_id, exc)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
index 1ca3a3c4a..6c1d9bc6b 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py
@@ -30,7 +30,7 @@ import json as _json
import logging
import time
-from sqlalchemy import select
+from sqlalchemy import delete, select
from repowise.core.persistence.database import get_session
from repowise.core.persistence.models import AnswerCache
@@ -65,8 +65,13 @@ from repowise.server.mcp_server._helpers import (
)
from repowise.server.mcp_server._meta import answer_hint as _answer_hint
from repowise.server.mcp_server._meta import build_meta as _build_meta
-from repowise.server.mcp_server.tool_answer.confidence import _answer_is_hedged
+from repowise.server.mcp_server.tool_answer.confidence import (
+ _answer_is_hedged,
+ _is_value_question,
+ _ungrounded_numbers,
+)
from repowise.server.mcp_server.tool_answer.config import (
+ _ANSWER_CACHE_TTL_DAYS,
_ANSWER_SCHEMA_VERSION,
_DOMINANCE_RATIO,
_ENRICH_TOP_N_HITS,
@@ -82,8 +87,12 @@ from repowise.server.mcp_server.tool_answer.retrieval import (
_intersection_boost,
_rerank_by_coverage,
)
+from repowise.server.mcp_server.tool_answer.retrieval import (
+ serialize_hits as _serialize_hits,
+)
from repowise.server.mcp_server.tool_answer.symbols import (
_extract_question_identifiers,
+ _extract_value_answer,
_hydrate_symbols_for_hits,
)
from repowise.server.mcp_server.tool_answer.synthesis import (
@@ -94,30 +103,48 @@ from repowise.server.mcp_server.tool_answer.synthesis import (
_log = logging.getLogger("repowise.mcp.answer")
+def _json_default(obj):
+ """Serialize the non-JSON types retrieval hits carry (``_sources`` sets).
+
+ Before this fallback existed, EVERY cache write failed on the sets the
+ hybrid retriever attaches to hits — silently, under the old blanket
+ suppress. The cache never stored a single post-hybrid-pipeline answer.
+ """
+ if isinstance(obj, (set, frozenset)):
+ # str-key the sort: a serializer whose whole job is "never fail the
+ # cache write" must not raise TypeError on a mixed-type set.
+ return sorted(obj, key=str)
+ return str(obj)
+
+
+def _cache_entry_expired(created_at) -> bool:
+ """True when an answer-cache row is older than the hard TTL."""
+ if created_at is None:
+ return False
+ from datetime import UTC, datetime, timedelta
+
+ ts = created_at if created_at.tzinfo else created_at.replace(tzinfo=UTC)
+ return (datetime.now(UTC) - ts) > timedelta(days=_ANSWER_CACHE_TTL_DAYS)
+
+
@mcp.tool()
async def get_answer(
question: str,
scope: str | None = None,
repo: str | None = None,
) -> dict:
- """Synthesised answer to a code question with verified citations and a calibrated trust signal.
+ """Synthesised answer with citations and a calibrated trust signal.
- The only tool that pairs RAG retrieval over the wiki with an LLM-written
- answer plus a separately-reported retrieval_quality. Use it as the first
- call on "how does X work" / "where is Y" / "why is Z structured this way"
- questions — it eliminates the search → context → read loop when retrieval
- is dominant. On low confidence it returns a structured ``best_guesses``
- list (one-line justifications per candidate) instead of an empty answer,
- so the caller always has somewhere concrete to Read next.
-
- Returns ``{answer, citations, confidence, retrieval_quality,
- fallback_targets, best_guesses?, next_action_hint?}``. Always verify cited
- paths exist if you intend to act on them.
+ First call for "how does X work" / "where is Y" / "why is Z" questions.
+ confidence=high is content-grounded (value + citation-source gates):
+ cite it directly, no verification Read needed. Low confidence returns
+ best_guesses with one-line justifications instead of an empty answer.
+ retrieval_quality separately rates the retrieval that fed synthesis.
Args:
question: developer question.
- scope: optional path prefix to restrict retrieval (e.g. "src/pkg/").
- repo: repository identifier; usually omitted.
+ scope: optional path-prefix filter (e.g. "src/pkg/").
+ repo: usually omitted.
"""
if repo == "all":
return _unsupported_repo_all("get_answer")
@@ -175,10 +202,23 @@ async def get_answer(
cached_paths = [
*(payload.get("citations") or []),
*(payload.get("fallback_targets") or []),
- *(h.get("target_path") for h in (payload.get("retrieval") or [])),
+ # "path" is the serialized key; "target_path" survives in
+ # rows cached before the clean retrieval view existed.
+ *(h.get("path") or h.get("target_path") for h in (payload.get("retrieval") or [])),
*(g.get("file") for g in (payload.get("best_guesses") or [])),
]
excluded_cache = any(is_excluded(p, exclude_spec) for p in cached_paths)
+ # Freshness: a row synthesised against a previous index may cite
+ # moved code or stale values. The write path stamps the repo's
+ # head commit into the persisted payload; a mismatch (or a row
+ # past the hard TTL, for pre-stamping rows and gitless repos)
+ # forces re-synthesis.
+ current_commit = getattr(repository, "head_commit", None)
+ cached_commit = payload.get("_indexed_commit")
+ stale_commit = bool(
+ cached_commit and current_commit and cached_commit != current_commit
+ )
+ expired = _cache_entry_expired(cached.created_at)
if schema_stale:
_log.info(
"Bypassing cache entry at schema v%s (current v%s)",
@@ -189,7 +229,19 @@ async def get_answer(
_log.info("Bypassing hedged cache entry for re-synthesis")
elif excluded_cache:
_log.info("Bypassing cache entry referencing a now-excluded path")
+ elif stale_commit:
+ _log.info(
+ "Bypassing cache entry from commit %s (repo now at %s)",
+ cached_commit,
+ current_commit,
+ )
+ elif expired:
+ _log.info("Bypassing cache entry past the %d-day TTL", _ANSWER_CACHE_TTL_DAYS)
else:
+ # Cache-internal fields never reach the consumer (response
+ # keys must not start with "_" except _meta).
+ payload.pop("_indexed_commit", None)
+ payload.pop("_schema_version", None)
payload["_meta"] = _build_meta(
timing_ms=(time.perf_counter() - t0) * 1000,
cached=True,
@@ -330,7 +382,7 @@ async def get_answer(
else "Fall back to search_codebase or Grep."
),
"fallback_targets": fallback_targets,
- "retrieval": hits[:_GATED_RETURN_HITS],
+ "retrieval": _serialize_hits(hits, limit=_GATED_RETURN_HITS),
"note": (
"Multiple plausible candidates — synthesis skipped to "
"avoid anchoring on a wrong frame. Each best_guess entry "
@@ -352,6 +404,42 @@ async def get_answer(
# dominant relational questions and pushes cost back onto the agent's
# own reasoning loop.
+ # --- Value-extraction fast path ----------------------------------------
+ # Value-shaped question + a question-matched constant in the top hits →
+ # the verbatim assignment line (read live by the hydrator) IS the
+ # answer. Today this class of question costs a multi-call drill-down
+ # chain and synthesis sometimes invents the number; the fast path is one
+ # call, zero LLM cost, and cannot hallucinate. Not cached: extraction is
+ # cheap and must always reflect the current source.
+ if _is_value_question(question) and question_ids:
+ extraction = _extract_value_answer(hits, question_ids)
+ if extraction is not None:
+ top_score_fp = hits[0].get("score", 0.0) if hits else 0.0
+ answer_text = extraction["answer"]
+ if extraction.get("value_source"):
+ answer_text += "\n\n" + extraction["value_source"]
+ return {
+ "answer": answer_text,
+ "citations": [extraction["file"]],
+ "confidence": "high",
+ "retrieval_quality": (
+ "high" if top_score_fp >= _HIGH_CONFIDENCE_SCORE_FLOOR else "partial"
+ ),
+ "grounding": "extracted",
+ "fallback_targets": fallback_targets,
+ "retrieval": [],
+ "note": (
+ "Extracted verbatim from the live source line — no LLM "
+ "synthesis involved. Cite directly; no verification "
+ "Read needed."
+ ),
+ "_meta": _build_meta(
+ timing_ms=(time.perf_counter() - t0) * 1000,
+ hint=_answer_hint("high", len(hits)),
+ repository=repository,
+ ),
+ }
+
# --- Synthesis (LLM) ---------------------------------------------------
provider = _resolve_provider_for_answer(getattr(ctx, "path", None))
if provider is None:
@@ -362,7 +450,7 @@ async def get_answer(
"citations": [],
"confidence": "low",
"fallback_targets": fallback_targets,
- "retrieval": hits,
+ "retrieval": _serialize_hits(hits),
"note": (
"No LLM provider configured (set REPOWISE_PROVIDER + API key). "
"Returning retrieval hits only — Read the listed files to answer."
@@ -412,7 +500,7 @@ async def get_answer(
"citations": [],
"confidence": "low",
"fallback_targets": fallback_targets,
- "retrieval": hits,
+ "retrieval": _serialize_hits(hits),
"note": f"LLM synthesis failed ({type(exc).__name__}). Read the listed files to answer.",
"_meta": _build_meta(
timing_ms=(time.perf_counter() - t0) * 1000,
@@ -428,6 +516,36 @@ async def get_answer(
# Fall back to top-2 retrieval paths so the agent always has something to verify.
citations = fallback_targets[:2]
+ # Line-grounded quotes: for symbols the answer actually names, attach the
+ # verbatim source line(s) the hydrator read live from disk. An agent can
+ # publish a cited claim backed by a quote without any verification Read —
+ # the quote IS the verification.
+ quotes: list[dict] = []
+ for h in hits[:_ENRICH_TOP_N_HITS]:
+ for s in h.get("symbols") or []:
+ name = s.get("name")
+ # Require a name long enough that substring containment is
+ # meaningful — a 1-2 char constant (``T``, ``e``) would "appear"
+ # in almost any answer and attach an irrelevant quote.
+ if not name or len(name) < 3 or name not in answer_text:
+ continue
+ src = s.get("source_excerpt") or s.get("signature") or ""
+ if not src:
+ continue
+ quote_lines = src.splitlines()[:3]
+ start = s.get("start_line") or 0
+ quotes.append(
+ {
+ "path": h.get("target_path"),
+ "lines": [start, start + len(quote_lines) - 1],
+ "quote": "\n".join(quote_lines),
+ }
+ )
+ if len(quotes) >= 5:
+ break
+ if len(quotes) >= 5:
+ break
+
# Compute confidence from the dominance ratio (top hit vs second hit).
# The dominance ratio is a more reliable separator than absolute BM25
# thresholds, which tend to label most retrievals "high" indiscriminately.
@@ -471,6 +589,27 @@ async def get_answer(
if not has_match:
confidence = "medium"
+ # Fourth gate — value grounding: on value-shaped questions (default /
+ # threshold / limit / how many), every number the answer asserts must
+ # appear somewhere in the material retrieval actually contained. A
+ # number synthesis produced from thin air is a factual error delivered
+ # with authority — the single worst calibration failure, because the
+ # consumer was told not to verify. Cap at low and say why.
+ ungrounded_values: list[str] = []
+ if not hedged and _is_value_question(question):
+ ungrounded_values = _ungrounded_numbers(answer_text, hits)
+ if ungrounded_values:
+ confidence = "low"
+
+ # Fifth gate — citation-source gate: a high-confidence answer must cite
+ # at least one page that contributed actual source material (hydrated
+ # symbols with signatures/bodies), not just file summaries. Summary-only
+ # grounding is how plausible-but-wrong syntheses get through.
+ if confidence == "high":
+ cited = set(citations)
+ if not any(h.get("symbols") for h in hits if h.get("target_path") in cited):
+ confidence = "medium"
+
# retrieval_quality is a separate signal from confidence. Where confidence
# says "how much should you trust the synthesised text", retrieval_quality
# says "how good was the retrieval that fed it". The agent uses confidence
@@ -489,7 +628,6 @@ async def get_answer(
# synthesis doesn't help them, and keeping it in the response bloats
# every follow-up turn's prompt cache.
payload = {
- "_schema_version": _ANSWER_SCHEMA_VERSION,
"answer": answer_text,
"citations": citations,
"confidence": "low",
@@ -502,16 +640,45 @@ async def get_answer(
),
}
else:
+ # Confidence-conditional retrieval block: the block exists so the
+ # agent can ground when the answer alone isn't trustworthy. At high
+ # confidence the citations + answer suffice — carrying five enriched
+ # hits through the conversation cache buys nothing. At medium the
+ # agent verifies the top candidates: two truncated hits, no symbol
+ # enrichment for graph-expansion neighbors. Low keeps the full
+ # block — that's when routing material earns its bytes.
+ if confidence == "high":
+ retrieval_view: list[dict] = []
+ elif confidence == "medium":
+ retrieval_view = _serialize_hits(
+ hits, limit=2, summary_chars=160, symbols_for_expanded=False
+ )
+ else:
+ retrieval_view = _serialize_hits(hits)
payload = {
- "_schema_version": _ANSWER_SCHEMA_VERSION,
"answer": answer_text,
"citations": citations,
"confidence": confidence,
"retrieval_quality": retrieval_quality,
"fallback_targets": fallback_targets,
- "retrieval": hits,
+ "retrieval": retrieval_view,
}
- if confidence == "high":
+ if quotes:
+ payload["quotes"] = quotes
+ if ungrounded_values:
+ payload["note"] = (
+ f"Value-grounding gate: the answer asserts {ungrounded_values} "
+ "but none of these appear in any retrieved excerpt — the "
+ "value(s) may be synthesised. Read "
+ f"{fallback_targets[0] if fallback_targets else 'the cited file'} "
+ "to confirm before citing a number."
+ )
+ if fallback_targets:
+ payload["next_action_hint"] = (
+ f"Read {fallback_targets[0]} and verify the asserted value(s) "
+ f"{ungrounded_values} against the live source."
+ )
+ elif confidence == "high":
payload["note"] = (
"High confidence: top retrieval result clearly dominates "
f"(dominance ratio {_ratio:.2f}x, top score {_top_score:.2f}) "
@@ -520,21 +687,39 @@ async def get_answer(
"is missing."
)
- # Persist to cache. Best-effort: cache failures must NEVER block the
- # response (we already have the answer in hand).
+ # Persist to cache (upsert). Best-effort: cache failures must never block
+ # the response — but they must be LOGGED, not suppressed. A plain INSERT
+ # under a blanket suppress violated uq_answer_cache_q on every
+ # bypass-and-resynthesize round and failed silently, so hedged/stale rows
+ # were never upgraded. Delete-then-insert in one transaction is the
+ # dialect-agnostic upsert; the stamped _indexed_commit drives the
+ # read-side freshness check.
if answer_text:
- with contextlib.suppress(Exception):
+ cache_payload = dict(payload)
+ cache_payload["_schema_version"] = _ANSWER_SCHEMA_VERSION
+ commit_now = getattr(repository, "head_commit", None)
+ if commit_now:
+ cache_payload["_indexed_commit"] = commit_now
+ try:
async with get_session(ctx.session_factory) as session:
+ await session.execute(
+ delete(AnswerCache).where(
+ AnswerCache.repository_id == repo_id,
+ AnswerCache.question_hash == qhash,
+ )
+ )
row = AnswerCache(
repository_id=repo_id,
question_hash=qhash,
question=question.strip(),
- payload_json=_json.dumps(payload),
+ payload_json=_json.dumps(cache_payload, default=_json_default),
provider_name=getattr(provider, "provider_name", "") or "",
model_name=getattr(provider, "model_name", "") or "",
)
session.add(row)
await session.commit()
+ except Exception as exc:
+ _log.warning("get_answer cache write failed: %s", exc)
payload["_meta"] = _build_meta(
timing_ms=(time.perf_counter() - t0) * 1000,
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py b/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
index 21dd56c6c..6edabb6c2 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/confidence.py
@@ -8,6 +8,8 @@ answer — is a pure predicate and lives here.
from __future__ import annotations
+import re
+
from repowise.server.mcp_server.tool_answer.config import _HEDGE_MARKERS
@@ -21,3 +23,68 @@ def _answer_is_hedged(answer_text: str) -> bool:
"""
low = (answer_text or "").lower()
return any(marker in low for marker in _HEDGE_MARKERS)
+
+
+# Question shapes that ask for a specific value: defaults, thresholds,
+# limits, counts. These are the questions where a confidently-asserted
+# number that retrieval never contained is a factual error, not a nuance.
+_VALUE_QUESTION_RE = re.compile(
+ r"\b(default|threshold|constant|limit|cap|max|min|value|timeout|"
+ r"how many|how much|how large|how big|how long)\b",
+ re.IGNORECASE,
+)
+
+# file.py:123 / file.py:123-145 — line refs the LLM adds for citations are
+# not value assertions and must not feed the grounding check.
+_FILE_LINE_REF_RE = re.compile(r"[\w./-]+:\d+(?:-\d+)?")
+
+# Standalone numbers (int or decimal). Lookarounds keep version-ish and
+# identifier-embedded digits (v2, utf-8, sha256, 2.5.1) out while still
+# matching sentence-final numbers ("the default is 3.").
+_NUMBER_RE = re.compile(r"(?<![\w.])-?\d+(?:\.\d+)?(?!\w)(?!\.\d)")
+
+# Digit-grouping separators: ``100_000`` (source) and ``100,000`` (prose) are
+# the same value as ``100000``. Strip them on both sides before comparing, or
+# a correct constant like ``MAX = 100_000`` reads as ungrounded against an
+# answer that says "100000" — a false downgrade on the exact value-shaped
+# constants this gate exists to protect.
+_THOUSANDS_SEP_RE = re.compile(r"(?<=\d)[,_](?=\d)")
+
+
+def _numbers_in(text: str) -> set[str]:
+ """Standalone numbers in *text*, with digit-grouping separators removed."""
+ return set(_NUMBER_RE.findall(_THOUSANDS_SEP_RE.sub("", text or "")))
+
+
+def _is_value_question(question: str) -> bool:
+ """True when the question asks for a concrete value."""
+ return bool(_VALUE_QUESTION_RE.search(question or ""))
+
+
+def _ungrounded_numbers(answer_text: str, hits: list[dict]) -> list[str]:
+ """Numbers the answer asserts that appear nowhere in the retrieval material.
+
+ The exact failure this guards: synthesis confidently inventing a default
+ ("the minimum count is 3") when no retrieved excerpt ever contained a 3.
+ Compares the answer's standalone numbers against the numbers present in
+ everything the LLM was shown for the hits — titles, summaries, snippets,
+ and hydrated symbols (signatures, docstrings, source excerpts).
+ """
+ text = _FILE_LINE_REF_RE.sub(" ", answer_text or "")
+ asserted = _numbers_in(text)
+ if not asserted:
+ return []
+
+ corpus_parts: list[str] = []
+ for h in hits or []:
+ for key in ("title", "summary", "snippet", "excerpt"):
+ v = h.get(key)
+ if v:
+ corpus_parts.append(str(v))
+ for s in h.get("symbols") or []:
+ for key in ("name", "signature", "docstring", "source_excerpt"):
+ v = s.get(key)
+ if v:
+ corpus_parts.append(str(v))
+ grounded = _numbers_in("\n".join(corpus_parts))
+ return sorted(asserted - grounded)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
index 2f9bd7ecb..3e0ded736 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/config.py
@@ -58,6 +58,19 @@ _HEDGE_MARKERS = (
"does not contain",
"is not contained",
"are not contained",
+ "do not include",
+ "does not include",
+ "not included in the",
+ "can't enumerate",
+ "cannot enumerate",
+ "can't determine",
+ "i can't",
+ "i cannot",
+ "not shown in",
+ "not shown here",
+ "material shown",
+ "not visible in",
+ "unable to determine",
"not contain sufficient",
"not contain enough",
"is not covered",
@@ -180,7 +193,16 @@ _HIGH_CONFIDENCE_SCORE_FLOOR = 1.5
# expansion, structured prelude, decision fusion). Cached v2 payloads were
# synthesised over weaker retrieval — bumping forces re-synthesis so the
# upgrade actually reaches callers without waiting for cache expiry.
-_ANSWER_SCHEMA_VERSION = 3
+# v4: confidence calibration gates (value-grounding, citation-source,
+# expanded hedge markers). Cached v3 confidence values predate the gates
+# and can carry confidently-asserted ungrounded values.
+_ANSWER_SCHEMA_VERSION = 4
+
+# Hard TTL on answer-cache rows. Commit-based invalidation (the payload's
+# stamped ``_indexed_commit`` vs the repo's current head) is the primary
+# freshness gate, but rows written before commit stamping existed — or for
+# repos without git metadata — need a backstop so they can't serve forever.
+_ANSWER_CACHE_TTL_DAYS = 14
# Intersection-retrieval connectives. If a question contains any of these
# (case-insensitive whole-word), it's likely a relational/multi-entity
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
index c5426f24c..eb17fcb1f 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
@@ -29,6 +29,50 @@ from repowise.server.mcp_server.tool_answer.config import (
)
+def serialize_hits(
+ hits: list[dict],
+ *,
+ limit: int | None = None,
+ summary_chars: int | None = None,
+ symbols_for_expanded: bool = True,
+) -> list[dict]:
+ """Agent-facing view of retrieval hits — content only, no plumbing.
+
+ Internal scoring fields (``_coverage``, ``_raw_score``, ``_sources``,
+ ``_pagerank``, …) and ``page_id`` are ranking debug an agent can do
+ nothing with; they were ~70% of a get_answer response by volume. Zero
+ information loss for the consumer: path, title, summary, snippet,
+ excerpt, score, and hydrated symbols all survive.
+
+ ``summary_chars`` truncates summaries (medium-confidence diet);
+ ``symbols_for_expanded=False`` drops symbol enrichment from hits that
+ only entered via 1-hop graph expansion (they are routing material, not
+ answer material).
+ """
+ out: list[dict] = []
+ for h in hits[: limit if limit is not None else len(hits)]:
+ entry: dict[str, Any] = {"path": h.get("target_path")}
+ if h.get("title"):
+ entry["title"] = h["title"]
+ summary = h.get("summary") or ""
+ if summary_chars is not None and len(summary) > summary_chars:
+ summary = summary[: summary_chars - 1].rstrip() + "…"
+ if summary:
+ entry["summary"] = summary
+ for key in ("snippet", "excerpt"):
+ if h.get(key):
+ entry[key] = h[key]
+ if h.get("score") is not None:
+ entry["score"] = round(h["score"], 3)
+ expanded = "graph_expand" in (h.get("_sources") or ())
+ if h.get("symbols") and (symbols_for_expanded or not expanded):
+ entry["key_symbols"] = [
+ {k: v for k, v in s.items() if not k.startswith("_")} for s in h["symbols"]
+ ]
+ out.append(entry)
+ return out
+
+
def _question_terms(question: str) -> list[str]:
"""Extract content terms from a question. Lowercase, alnum-tokenized,
stopwords + length<3 dropped. Used by the term-coverage re-ranker."""
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
index 1669fbf5b..b929b829a 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/symbols.py
@@ -139,6 +139,45 @@ def _read_signature_from_source(
return " ".join(sig_lines)
+def _extract_value_answer(hits: list[dict], question_ids: set[str]) -> dict | None:
+ """Verbatim-assignment answer for value-shaped questions (the C1 fast path).
+
+ When a question names an identifier and the hydrator matched a
+ constant/variable symbol in the top hits, the symbol's signature IS the
+ answer — the verbatim assignment line read from live source. No LLM
+ call, nothing to hedge, nothing to invent. Exact name matches win over
+ substring matches.
+ """
+ qids_lower = {q.lower() for q in question_ids}
+ candidates: list[dict] = []
+ for h in hits[:_ENRICH_TOP_N_HITS]:
+ path = h.get("target_path")
+ if not path:
+ continue
+ for s in h.get("symbols") or []:
+ if not s.get("_matched") or s.get("kind") not in ("constant", "variable"):
+ continue
+ sig = s.get("signature") or ""
+ if "=" not in sig:
+ continue
+ entry = {
+ "name": s.get("name"),
+ "signature": sig,
+ "file": path,
+ "line": s.get("start_line"),
+ "answer": f"{sig} ({path}:{s.get('start_line')})",
+ }
+ # Multi-line values (dicts/arrays): the hydrator attached the
+ # live body — include it so the agent never needs a follow-up.
+ excerpt = s.get("source_excerpt")
+ if excerpt and excerpt.strip() != sig.strip():
+ entry["value_source"] = excerpt
+ if (s.get("name") or "").lower() in qids_lower:
+ return entry
+ candidates.append(entry)
+ return candidates[0] if candidates else None
+
+
async def _hydrate_symbols_for_hits(
session,
repo_id: str,
@@ -188,7 +227,13 @@ async def _hydrate_symbols_for_hits(
by_file: dict[str, list[dict]] = {}
repo_root = Path(str(ctx.path)) if ctx and ctx.path else None
for row in res.scalars().all():
- rich_sig = _read_signature_from_source(repo_root, row.file_path, row.start_line)
+ # Constants/variables: the stored signature IS the verbatim assignment
+ # line. The disk re-read below walks forward looking for a ":"-closed
+ # def line and would join unrelated following lines for assignments.
+ if row.kind in ("constant", "variable"):
+ rich_sig = None
+ else:
+ rich_sig = _read_signature_from_source(repo_root, row.file_path, row.start_line)
# Does the symbol name match any identifier from the question?
name_lower = (row.name or "").lower()
qname_lower = (row.qualified_name or "").lower()
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/context.py b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
index e269a53bc..a70ba1c20 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/context.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
@@ -54,42 +54,18 @@ async def get_context(
) -> dict:
"""Triage card for files / modules / symbols — relationships, not source bytes.
- Returns a compact card the agent can use to decide its next move: title,
- summary, signatures, hotspot bit, top callers, and pointers (decision_record
- titles, symbol_ids) into the deeper tools. For the actual source body of a
- symbol, call ``get_symbol("path/to/file.py::Name")`` — it is cheaper than
- Read and returns bounded bytes with exact line numbers.
-
- Batch multiple targets in one call. In workspace mode responses are
- auto-enriched with cross-repo co-change partners and API contract links.
-
- Include options (everything outside defaults is opt-in):
- - "full_doc": full wiki markdown content for the target
- - "ownership": primary owner, bus factor, contributor count
- - "last_change":last commit date and author
- - "callers": who calls this symbol (symbol targets only)
- - "callees": what this symbol calls (symbol targets only)
- - "metrics": PageRank, betweenness centrality, percentile ranks
- - "community": architectural community membership + neighbors
- - "decisions": full decision records (default returns titles only)
- - "skeleton": the file with bodies elided — every signature kept, the
- bodies of the highest-PageRank symbols inlined under a
- token budget. A fraction of the cost of Read for
- structure-level questions (file targets only).
- DEFAULT for file targets above ~80 lines: the skeleton
- replaces the bare symbol list (strictly better per
- token). Pass compact=False for the symbol-list card.
- A ``mostly_full`` flag marks files where a direct Read
- costs little more.
-
- Example: get_context(["src/auth/service.py", "src/auth/middleware.py"])
- Example: get_context(["src/auth/service.py::verify_token"], include=["callers"])
+ Returns title, summary, signatures, hotspot bit, decision_record titles,
+ and symbol_ids to pipe into get_symbol (cheaper than Read for bodies).
+ Batch targets in one call. File targets above ~80 lines default to a
+ skeleton (every signature + top-PageRank bodies, with a verified flag —
+ a fraction of Read cost); ``mostly_full`` marks files where a direct
+ Read costs little more.
Args:
- targets: file paths, module paths, or qualified symbol IDs.
- include: list of optional data blocks (defaults are always returned).
- compact: default True (signatures only; large file targets auto-upgrade
- to skeleton). False adds structure+imports+docstrings instead.
+ targets: file paths, module paths, or "path::Symbol" ids.
+ include: opt-in blocks: full_doc | ownership | last_change | callers
+ | callees | metrics | community | decisions | skeleton.
+ compact: default True; False adds structure+imports+docstrings.
repo: usually omitted.
"""
if repo == "all":
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
index 26fee7162..92b21afb5 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
@@ -69,7 +69,14 @@ async def _resolve_call_graph(
node = next((r for r in rows if r.file_path == file_hint), rows[0])
if node is None or node.node_type != "symbol":
- # For file targets, return empty with explanation — callers/callees is symbol-only
+ # File targets get the rolled-up view instead of an empty block —
+ # an empty callers list forced a second round-trip per orientation
+ # pass for no reason; the graph has the answer at file granularity.
+ if node is not None and node.node_type == "file" and want_callers:
+ await _resolve_file_level_callers(session, repo_id, node, result_data, exclude_spec)
+ if want_callees:
+ result_data["callees"] = []
+ return
if want_callers:
result_data["callers"] = []
if want_callees:
@@ -144,6 +151,80 @@ async def _resolve_call_graph(
result_data["callees"] = callees
+async def _resolve_file_level_callers(
+ session: AsyncSession,
+ repo_id: str,
+ node: GraphNode,
+ result_data: dict[str, Any],
+ exclude_spec: Any = None,
+) -> None:
+ """File-target callers: importing files + inbound symbol-call rollup.
+
+ Two granularities merged per caller file: ``imports: true`` when the
+ file imports this one, ``inbound_calls`` counting cross-file call edges
+ into any symbol defined here.
+ """
+ from repowise.core.persistence.models import GraphEdge
+
+ # Who imports this file (file-node inbound import edges).
+ import_edges = await get_graph_edges_for_node(
+ session, repo_id, node.node_id, direction="callers", edge_types=["imports"], limit=50
+ )
+ importer_ids = [e.source_node_id for e in import_edges if e.target_node_id == node.node_id]
+ importer_nodes = await get_graph_nodes_by_ids(session, repo_id, importer_ids)
+ # For file nodes the node_id IS the path; file_path may be unset.
+ importer_files = {
+ (n.file_path or n.node_id)
+ for n in importer_nodes.values()
+ if n is not None and (n.file_path or n.node_id)
+ }
+
+ # Cross-file calls into any symbol defined in this file, rolled up by
+ # the calling file.
+ target_file = node.file_path or node.node_id
+ sym_res = await session.execute(
+ select(GraphNode.node_id).where(
+ GraphNode.repository_id == repo_id,
+ GraphNode.node_type == "symbol",
+ GraphNode.file_path == target_file,
+ )
+ )
+ sym_ids = [row[0] for row in sym_res.all()]
+ calls_by_file: dict[str, int] = {}
+ if sym_ids:
+ edge_res = await session.execute(
+ select(GraphEdge.source_node_id, GraphEdge.confidence).where(
+ GraphEdge.repository_id == repo_id,
+ GraphEdge.target_node_id.in_(sym_ids),
+ GraphEdge.edge_type == "calls",
+ )
+ )
+ for src_id, confidence in edge_res.all():
+ if (confidence or 0) < _MIN_CALL_CONFIDENCE:
+ continue
+ src_file = src_id.split("::")[0] if "::" in src_id else src_id
+ if src_file == target_file:
+ continue # intra-file calls are not "callers" of the file
+ calls_by_file[src_file] = calls_by_file.get(src_file, 0) + 1
+
+ entries: list[dict[str, Any]] = []
+ for f in sorted(importer_files | set(calls_by_file)):
+ entry: dict[str, Any] = {"file": f}
+ if f in importer_files:
+ entry["imports"] = True
+ if calls_by_file.get(f):
+ entry["inbound_calls"] = calls_by_file[f]
+ entries.append(entry)
+ entries = filter_dicts_by_key(entries, "file", exclude_spec)
+ entries.sort(key=lambda x: -(x.get("inbound_calls") or 0))
+
+ result_data["callers"] = entries[:20]
+ result_data["_call_graph_note"] = (
+ "File-level rollup: importing files plus inbound cross-file call "
+ "counts. For symbol-precise callers pass 'file.py::Symbol'."
+ )
+
+
async def _resolve_metrics(
session: AsyncSession,
repository: Repository,
@@ -426,6 +507,10 @@ async def _resolve_skeleton(
"pct_of_full": round(result.pct_of_full, 1),
"bodies_kept": list(result.bodies_kept),
"text": result.text,
+ # The skeleton is rendered from the live source file read above —
+ # its text is fresh by construction. Part of the trust contract:
+ # a verified response never needs a follow-up Read.
+ "verified": True,
}
if result.mode == "raw":
result_data["skeleton"]["note"] = (
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
index f7b6f1416..129cd215e 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -329,6 +329,24 @@ async def _resolve_one_target(
result_data["target"] = target
result_data["type"] = target_type
+ # Tombstone redirect: the page documents a file deleted or renamed since
+ # indexing. A "fresh" card here is an active trap — return the redirect
+ # instead of the card.
+ if page is not None and getattr(page, "freshness_status", "") == "tombstone":
+ import json as _json_ts
+
+ try:
+ successors = _json_ts.loads(page.metadata_json or "{}").get("successor_paths") or []
+ except (ValueError, TypeError):
+ successors = []
+ result_data["error"] = (
+ f"'{target}' was deleted or renamed after indexing — this page is a tombstone."
+ )
+ if successors:
+ result_data["successor_paths"] = successors
+ result_data["hint"] = f"Content moved; call get_context on {successors[0]!r} instead."
+ return result_data
+
want_skeleton = bool(include and "skeleton" in include)
auto_skeleton = False
diff --git a/packages/server/src/repowise/server/mcp_server/tool_dead_code.py b/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
index 5ea724e40..36441bf44 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
@@ -1,4 +1,4 @@
-"""MCP Tool 7: get_dead_code — tiered refactor plan for unused code."""
+"""MCP Tool 7: get_dead_code — tiered refactor plan for unused code."""
from __future__ import annotations
@@ -46,55 +46,26 @@ async def get_dead_code(
no_unreachable: bool = False,
no_unused_exports: bool = False,
) -> dict:
- """Unused exports, unreachable files, zombie packages — what grep cannot tell you.
-
- Static reachability analysis the agent cannot derive from imports alone.
- Returns findings tiered by confidence (high = zero refs; medium = likely
- unused; low = check first) with per-directory and per-owner rollups so a
- cleanup sprint can prioritise. In workspace mode, cross-repo consumer
- detection lowers confidence on findings that other repos import.
-
- Use group_by="directory" for a directory-level overview, or
- group_by="owner" to see who owns the most dead code. Use tier
- to focus on a single confidence band.
-
- Scan scope flags (mirror the DeadCodeAnalyzer.analyze config):
- - Use ``min_confidence=0.7`` for high-confidence cleanups — filters out
- speculative findings and surfaces only code with zero references that
- hasn't been touched in months. Ideal before a release or refactor sprint.
- - Use ``include_internals=True`` for aggressive scans of private symbols
- (functions/variables prefixed with _ or declared without exports). This
- has a higher false-positive rate and is off by default; enable it when
- doing a thorough dead-code purge of a stable, well-tested module.
- - Use ``no_unreachable=True`` to skip file-level reachability checks and
- focus only on symbol-level findings (unused exports/internals).
- - Use ``no_unused_exports=True`` to skip public-export checks, e.g. when
- you know the repo exposes a public API consumed externally.
- - Use ``include_zombie_packages=False`` to suppress monorepo package
- findings, useful in repos where cross-package imports are intentionally
- absent during development.
+ """Unused exports, unreachable files, zombie packages — tiered by confidence.
+
+ Run before a cleanup sprint, not a targeted fix. Findings tier
+ high/medium/low with per-directory and per-owner rollups; workspace
+ mode lowers confidence on findings other repos import.
Args:
- repo: Repository path, name, or ID.
- kind: Filter by kind (unreachable_file, unused_export, unused_internal, zombie_package).
- min_confidence: Minimum confidence threshold (default 0.5). Use 0.7 for high-confidence
- cleanups only.
- safe_only: Only return deletion-ready findings — high confidence with no runtime-load
- risk factors (config/bootstrap/database/environment/script files are excluded even
- when persisted as safe). Default false.
- limit: Maximum findings per tier (default 20). Clamped to 25 because larger
- payloads exceed MCP transport token caps; paginate by tier/directory/owner
- for deeper exploration.
- tier: Focus on a single tier: "high" (>=0.8), "medium" (0.5-0.8), or "low" (<0.5).
- directory: Filter findings to a specific directory prefix.
- owner: Filter findings by primary owner name.
- group_by: "directory" for per-directory rollup, "owner" for ownership hotspots.
- include_internals: Include unused private/internal symbol findings (default false).
- Enable for aggressive scans of private symbols.
- include_zombie_packages: Include zombie-package findings for monorepo packages with
- no external importers (default true).
- no_unreachable: Suppress unreachable-file findings (default false).
- no_unused_exports: Suppress unused-export findings (default false).
+ repo: usually omitted.
+ kind: unreachable_file | unused_export | unused_internal | zombie_package.
+ min_confidence: floor, default 0.5 (0.7 = cleanup-ready only).
+ safe_only: deletion-ready findings only (no runtime-load risk).
+ limit: max findings per tier (clamped to 25).
+ tier: "high" (>=0.8) | "medium" | "low".
+ directory: path-prefix filter.
+ owner: primary-owner filter.
+ group_by: "directory" | "owner" rollup.
+ include_internals: also scan private symbols (more false positives).
+ include_zombie_packages: monorepo package findings (default true).
+ no_unreachable: skip file-level reachability findings.
+ no_unused_exports: skip public-export findings.
"""
# MCP transport rejects payloads above ~25k tokens. A single serialized
# finding is ~400 chars, so 3 tiers x ~25 findings keeps us under budget
diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.py
index cf11bd2f4..f8b62d5ca 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py
@@ -330,9 +330,7 @@ async def get_overview(repo: str | None = None) -> dict:
GitMetadata.repository_id == repository.id,
)
)
- all_git = filter_rows_by_attr(
- list(git_res.scalars().all()), "file_path", exclude_spec
- )
+ all_git = filter_rows_by_attr(list(git_res.scalars().all()), "file_path", exclude_spec)
git_health: dict[str, Any] = {}
if all_git:
@@ -469,9 +467,7 @@ async def get_overview(repo: str | None = None) -> dict:
if p.lower() not in generic_labels and p not in ("src",):
dir_counts[p] += 1
break
- display_label = (
- dir_counts.most_common(1)[0][0] if dir_counts else f"cluster_{cid}"
- )
+ display_label = dir_counts.most_common(1)[0][0] if dir_counts else f"cluster_{cid}"
community_summary.append(
{
@@ -712,6 +708,25 @@ async def get_overview(repo: str | None = None) -> dict:
if ws_footer:
result["workspace"] = ws_footer
+ # Composition recipes live HERE (one overview call per session) so
+ # the per-tool docstrings — paid on every fresh agent — stay terse.
+ result["tool_guide"] = {
+ "first_call": "get_answer for any how/where/why question; trust "
+ "confidence=high directly (it is content-grounded).",
+ "reading_code": "get_context skeleton (≈37% of a full Read) → "
+ "get_symbol for bodies (verified: true = no re-read needed). "
+ "Raw Read only for files marked mostly_full or unservable.",
+ "recipes": [
+ "get_answer low confidence → Read best_guesses[0].file",
+ "get_context hotspot: true → get_risk before editing",
+ "get_context decision_records → get_why(targets=[...]) for rationale",
+ "PR review → get_risk(targets, changed_files) and read directive first",
+ "search_codebase grep_hint present → prefer Grep for those identifiers",
+ ],
+ "reread_triggers": "Only re-read source on bounds: approximate, "
+ "stale_warning in _meta, or search_method: bm25.",
+ }
+
result["_meta"] = _build_meta(repository=repository)
collector.attach(result)
return result
diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk.py b/packages/server/src/repowise/server/mcp_server/tool_risk.py
index bda0c0a8e..e4d07dc73 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_risk.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_risk.py
@@ -452,34 +452,18 @@ async def get_risk(
repo: str | None = None,
changed_files: list[str] | None = None,
) -> dict:
- """What history says about touching these files — hotspot, churn, owners, blast radius.
+ """What history says about touching these files — churn, owners, blast radius.
- The only tool that fuses git temporal signals (churn percentile, trend,
- bus factor) with graph topology (dependents, co-changes, impact surface)
- and security findings into one decision-shaped payload. Consult before
- editing any file in the 95th+ churn percentile or before merging a
- multi-file PR.
-
- Per-file fields: ``hotspot_score``, ``trend``, ``risk_type``,
- ``impact_surface`` (top 3), ``dependents_count``, ``co_change_partners``,
- ``primary_owner``, ``bus_factor``, ``test_gap``, ``security_signals``.
-
- Pass ``changed_files`` for PR-blast-radius mode. The response then carries
- a ``directive`` block — three short lists the caller can read in one
- glance (``will_break``, ``missing_cochanges``, ``missing_tests``) — plus
- the trimmed full ``pr_blast_radius`` dossier for deeper review. Global
- hotspots are omitted in PR mode (irrelevant to the diff) and re-included
- when ``changed_files`` is absent.
-
- In workspace mode, cross-repo consumers and API contract links bump the
- dependents count and appear in ``cross_repo_impact``.
-
- Example: get_risk(["src/auth/service.py"], changed_files=["src/auth/service.py"])
+ Fuses git temporal signals (churn percentile, trend, bus factor) with
+ graph topology (dependents, co-changes, impact surface) and security
+ findings. Consult before editing 95th+ churn-percentile files. Pass
+ changed_files for PR mode: the response leads with a directive block
+ (will_break, missing_cochanges, missing_tests) — read it first.
Args:
- targets: List of file paths to assess (standard per-file risk).
- repo: Repository path, name, or ID.
- changed_files: Optional list of files changed in a PR for blast-radius analysis.
+ targets: file paths to assess.
+ repo: usually omitted.
+ changed_files: PR-changed files for blast-radius mode.
"""
if repo == "all":
return _unsupported_repo_all("get_risk")
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.py
index d6341a468..f4d1262a0 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_search.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py
@@ -1,4 +1,4 @@
-"""MCP Tool 5: search_codebase — semantic search over the wiki."""
+"""MCP Tool 5: search_codebase — semantic search over the wiki."""
from __future__ import annotations
@@ -46,6 +46,19 @@ def _looks_like_exact_token(query: str) -> bool:
return bool(_IDENT_QUERY_RE.match(stripped))
+# Identifier-shaped tokens inside a longer query: snake_case of any casing
+# (≥1 underscore, incl. _UPPER_SNAKE constants) or CamelCase (≥2 humps).
+# Plain English words never match.
+_IDENT_TOKEN_RE = re.compile(
+ r"\b(?:_*[A-Za-z0-9]+_[A-Za-z0-9_]+|[A-Z][a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)+)\b"
+)
+
+
+def _embedded_identifiers(query: str) -> list[str]:
+ """Identifier-shaped tokens carried inside a natural-language query."""
+ return _IDENT_TOKEN_RE.findall(query)
+
+
# Decision records are short, dense title-statements; they win cosine
# similarity against long file-page embeddings on any query containing
# design nouns ("store", "SQLite", "cap", "prune") and crowd file pages
@@ -72,9 +85,81 @@ def _downweight_decisions(output: list[dict], query: str) -> None:
return
for item in output:
if item.get("page_type") == "decision_record" and item.get("relevance_score"):
- item["relevance_score"] = round(
- item["relevance_score"] * _DECISION_DOWNWEIGHT, 4
- )
+ item["relevance_score"] = round(item["relevance_score"] * _DECISION_DOWNWEIGHT, 4)
+
+
+def _sort_demoting_decisions(output: list[dict], query: str) -> None:
+ """Sort by relevance, ranking decision records below every file-backed
+ page on non-why queries.
+
+ The multiplicative down-weight alone is washed out when decision scores
+ dominate (short dense titles win cosine similarity by a margin > the
+ 0.6 factor) — observed live as 5/5 irrelevant decisions for a plain
+ implementation query. For non-why queries a decision record is never a
+ better first Read than a file page, so the demotion is absolute; the
+ down-weighted score still orders decisions among themselves.
+ """
+ why = _is_why_shaped(query)
+
+ def key(item: dict) -> tuple:
+ demoted = (not why) and item.get("page_type") == "decision_record"
+ return (1 if demoted else 0, -(item.get("relevance_score") or 0.0))
+
+ output.sort(key=key)
+
+
+async def _non_decision_fallback(ctx, query: str, fetch_limit: int) -> list[dict]:
+ """Wider re-fetch keeping only non-decision pages.
+
+ Guard for the window-saturation failure: when the entire over-fetched
+ window is decision records, demotion has nothing to promote and a
+ non-why query returns zero implementation pages. Fetch 4x wider, drop
+ decisions, and let the caller merge the survivors.
+ """
+ results = []
+ with contextlib.suppress(TimeoutError, Exception):
+ results = await asyncio.wait_for(
+ ctx.vector_store.search(query, limit=fetch_limit * 4),
+ timeout=8.0,
+ )
+ if not results:
+ with contextlib.suppress(Exception):
+ results = await ctx.fts.search(query, limit=fetch_limit * 4)
+
+ out = []
+ for r in results:
+ if r.page_type == "decision_record":
+ continue
+ if r.score < _MIN_RELEVANCE_SCORE:
+ continue
+ out.append(
+ {
+ "page_id": r.page_id,
+ "title": r.title,
+ "page_type": r.page_type,
+ "snippet": r.snippet,
+ "relevance_score": r.score,
+ }
+ )
+ return out
+
+
+async def _rescue_all_decision_window(
+ ctx, output: list[dict], query: str, fetch_limit: int
+) -> list[dict]:
+ """Merge non-decision pages into an all-decision result window.
+
+ No-op unless the query is non-why AND every current hit is a decision
+ record. Deduplicates by page_id.
+ """
+ if not output or _is_why_shaped(query):
+ return output
+ if not all(item.get("page_type") == "decision_record" for item in output):
+ return output
+ fallback = await _non_decision_fallback(ctx, query, fetch_limit)
+ seen = {item["page_id"] for item in output}
+ output.extend(item for item in fallback if item["page_id"] not in seen)
+ return output
def _fetch_limit_for(limit: int, kind: str | None) -> int:
@@ -94,9 +179,22 @@ def _fetch_limit_for(limit: int, kind: str | None) -> int:
# ``other`` and is dropped only when the caller asked for a specific kind.
_TEST_PATH_TOKENS = ("/test/", "/tests/", "/__tests__/", "test_", "_test.", ".spec.", ".test.")
_CONFIG_PATH_TOKENS = (
- "pyproject.toml", "package.json", "tsconfig", "setup.py", "setup.cfg",
- "/.github/", "dockerfile", ".yml", ".yaml", ".toml", ".ini", ".cfg",
- "lockfile", "package-lock", "uv.lock", "poetry.lock",
+ "pyproject.toml",
+ "package.json",
+ "tsconfig",
+ "setup.py",
+ "setup.cfg",
+ "/.github/",
+ "dockerfile",
+ ".yml",
+ ".yaml",
+ ".toml",
+ ".ini",
+ ".cfg",
+ "lockfile",
+ "package-lock",
+ "uv.lock",
+ "poetry.lock",
)
@@ -160,16 +258,19 @@ async def _search_single_repo(
continue
if r.score < _MIN_RELEVANCE_SCORE:
continue
- output.append({
- "page_id": r.page_id,
- "title": r.title,
- "page_type": r.page_type,
- "snippet": r.snippet,
- "relevance_score": r.score,
- })
+ output.append(
+ {
+ "page_id": r.page_id,
+ "title": r.title,
+ "page_type": r.page_type,
+ "snippet": r.snippet,
+ "relevance_score": r.score,
+ }
+ )
_downweight_decisions(output, query)
- output.sort(key=lambda x: x.get("relevance_score", 0), reverse=True)
+ output = await _rescue_all_decision_window(ctx, output, query, fetch_limit)
+ _sort_demoting_decisions(output, query)
# Attach target_path and drop excluded hits per repo (so federated search
# honours each repo's own exclude_patterns) before aggregation. Runs on
@@ -178,16 +279,22 @@ async def _search_single_repo(
page_ids = [item["page_id"] for item in output]
async with get_session(ctx.session_factory) as session:
res = await session.execute(
- select(Page.id, Page.target_path).where(Page.id.in_(page_ids))
+ select(Page.id, Page.target_path, Page.freshness_status).where(
+ Page.id.in_(page_ids)
+ )
)
- page_info = {row[0]: row[1] for row in res.all()}
+ rows = res.all()
+ page_info = {row[0]: row[1] for row in rows}
+ tombstoned = {row[0] for row in rows if row[2] == "tombstone"}
+ output = [item for item in output if item["page_id"] not in tombstoned]
for item in output:
item["target_path"] = page_info.get(item["page_id"], "")
output = filter_dicts_by_key(output, "target_path", _get_exclude_spec(ctx.path))
if kind:
output = [
- item for item in output
+ item
+ for item in output
if _classify_hit_kind(item.get("target_path", ""), item.get("page_type", "")) == kind
]
@@ -233,25 +340,18 @@ async def search_codebase(
) -> dict:
"""Find pages by concept — semantic search across the wiki.
- The right tool when ``get_answer`` punted and you need candidate files for
- a conceptual query ("authentication flow", "rate limiting", "where do we
- handle webhooks"). For exact identifiers or token matches, use Grep — it
- is faster and never drifts thematically. This tool will surface a Grep
- hint when the query looks like a bare identifier.
-
- Each result carries ``search_method`` (``"embedding"`` or ``"bm25"``) so
- the caller can tell whether semantic retrieval succeeded or fell back to
- keyword scoring; BM25 hits warrant more verification than embedding hits.
+ For conceptual queries ("rate limiting", "where do we handle webhooks")
+ when you don't know the file. For exact identifiers use Grep —
+ identifier-bearing queries get a grep_hint. Results carry search_method
+ ("embedding", or "bm25" fallback: verify those). Decision records rank
+ below file pages unless the query is why-shaped.
Args:
- query: natural-language search query.
- limit: maximum number of results to return (default 5).
- page_type: filter on page kind (``file_page``, ``module_page``,
- ``symbol_spotlight``).
- kind: filter by file role: ``"implementation"`` | ``"test"`` |
- ``"config"`` | ``"doc"``. Path-prefix heuristic; trims the result
- list rather than rewriting the query.
- repo: repository alias, or ``"all"`` for workspace-wide search.
+ query: natural-language query.
+ limit: max results (default 5).
+ page_type: file_page | module_page | symbol_spotlight.
+ kind: implementation | test | config | doc.
+ repo: alias, or "all" for workspace-wide.
"""
grep_hint: str | None = None
if _looks_like_exact_token(query):
@@ -260,6 +360,13 @@ async def search_codebase(
"literal usages faster and without thematic drift. This tool ran "
"the search anyway — verify before relying on the results."
)
+ elif idents := _embedded_identifiers(query):
+ shown = ", ".join(repr(t) for t in idents[:3])
+ grep_hint = (
+ f"Query names identifier(s) {shown} — for their exact "
+ "definition/usages, Grep is faster and never drifts "
+ "thematically. Semantic results below are concept-level."
+ )
if repo == "all":
# kind is filtered per-repo inside _search_single_repo, before each
@@ -316,15 +423,28 @@ async def search_codebase(
)
_downweight_decisions(output, query)
+ rescued = await _rescue_all_decision_window(ctx, output, query, fetch_limit)
+ if len(rescued) > len(output):
+ # Fallback entries enter after the method was determined; they came
+ # from the same backend.
+ for item in rescued:
+ item.setdefault("search_method", search_method)
+ output = rescued
# Batch-lookup page target paths for the kind filter + git freshness boost
if output:
page_ids = [item["page_id"] for item in output]
async with get_session(ctx.session_factory) as session:
res = await session.execute(
- select(Page.id, Page.target_path).where(Page.id.in_(page_ids))
+ select(Page.id, Page.target_path, Page.freshness_status).where(
+ Page.id.in_(page_ids)
+ )
)
- page_info = {row[0]: row[1] for row in res.all()}
+ rows = res.all()
+ page_info = {row[0]: row[1] for row in rows}
+ tombstoned = {row[0] for row in rows if row[2] == "tombstone"}
+ # Tombstoned pages document deleted/renamed files — never results.
+ output = [item for item in output if item["page_id"] not in tombstoned]
# Build git freshness map for result file paths — once for the
# whole batch, not per item.
@@ -358,14 +478,15 @@ async def search_codebase(
recency = 0.0
item["relevance_score"] = round(item["relevance_score"] * (1 + 0.2 * recency), 4)
- # Re-sort by boosted relevance
- output.sort(key=lambda x: x.get("relevance_score", 0), reverse=True)
+ # Re-sort by boosted relevance, decisions hard-demoted on non-why queries
+ _sort_demoting_decisions(output, query)
# Kind filter runs on the over-fetched list BEFORE the limit cut so the
# caller still gets up to ``limit`` results of the requested kind.
if kind:
output = [
- item for item in output
+ item
+ for item in output
if _classify_hit_kind(item.get("target_path", ""), item.get("page_type", "")) == kind
]
diff --git a/packages/server/src/repowise/server/mcp_server/tool_symbol.py b/packages/server/src/repowise/server/mcp_server/tool_symbol.py
index f3086e3e3..62ec536e8 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_symbol.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_symbol.py
@@ -1,4 +1,4 @@
-"""MCP Tool: get_symbol — byte-precise source retrieval for a single symbol.
+"""MCP Tool: get_symbol — byte-precise source retrieval for a single symbol.
This is the structural counterpart to get_context. Where get_context returns
file-level narrative (summary, symbol list, importers), get_symbol returns
@@ -11,8 +11,10 @@ Why a separate tool instead of "include source" on get_context?
cached prompt prefix by ~10x when the agent only needs one symbol.
* Predictability: response size is bounded by the symbol size, never the
file size — no surprise 50 KB payloads.
- * No reparsing: the bytes come straight from disk via the persisted line
- range. Tree-sitter never runs at retrieval time.
+ * Verified bounds: the persisted line range is checked against the live
+ file before serving (name-on-definition-line gate); on mismatch the
+ file is re-parsed once, the bounds corrected and healed in the DB. A
+ ``verified: true`` response never needs a follow-up Read.
The tool is intentionally additive — get_context remains the right call for
"explain this file" or "what's the relationship between A and B" questions.
@@ -56,6 +58,7 @@ from repowise.server.mcp_server._helpers import (
)
from repowise.server.mcp_server._meta import build_meta as _build_meta
from repowise.server.mcp_server._meta import symbol_hint as _symbol_hint
+from repowise.server.mcp_server._verify import check_symbol_bounds, heal_symbol_row
_log = __import__("logging").getLogger("repowise.mcp.symbol")
@@ -67,6 +70,21 @@ _MAX_SOURCE_LINES = 400
# "{path}::{name}" symbol_id. Also tolerates a pasted whole marker.
_OMISSION_REF_RE = re.compile(r"^repowise#([0-9a-f]{12})$")
+# Range-read dispatch: "path/to/file.py:140-180". A single colon followed by
+# a numeric range never collides with "{path}::{name}" (double colon) or an
+# omission ref. The escape hatch for everything not indexed as a symbol —
+# imports, module docstrings, decorators between symbols — without falling
+# back to a whole-file Read.
+_RANGE_ID_RE = re.compile(r"^(?P<path>.+?):(?P<start>\d+)-(?P<end>\d+)$")
+
+# Range reads are bounded tighter than symbol reads: the caller names exact
+# lines, so a large range is a deliberate choice to cap.
+_MAX_RANGE_LINES = 200
+
+# Dead-end recovery: max grep matches returned when a symbol lookup misses
+# but the file exists on disk.
+_MAX_FALLBACK_MATCHES = 8
+
def _extract_omission_ref(symbol_id: str) -> str | None:
"""Return the 12-hex omission ref when *symbol_id* is ref-shaped, else None."""
@@ -144,6 +162,97 @@ def _resolve_omission_ref(
return response
+async def _resolve_range_read(
+ symbol_id: str, path: str, start: int, end: int, context_lines: int, ctx: Any, t0: float
+) -> dict:
+ """Serve a live, bounded line-range read: "path/to/file.py:140-180".
+
+ Always ``verified: true`` — the bytes come straight from the live file
+ at the requested lines. Bounded to _MAX_RANGE_LINES; the full-file token
+ count is declared as the counterfactual (the Read this call replaced).
+ """
+ repository = None
+ async with get_session(ctx.session_factory) as session:
+ repository = await _get_repo(session)
+
+ def _err(msg: str) -> dict:
+ return {
+ "symbol_id": symbol_id,
+ "error": msg,
+ "_meta": _build_meta(
+ timing_ms=(time.perf_counter() - t0) * 1000, repository=repository
+ ),
+ }
+
+ if is_excluded(path, _get_exclude_spec(ctx.path)):
+ return _err(f"'{path}' is excluded from indexing.")
+ if not ctx.path:
+ return _err("MCP server has no repo path configured")
+
+ text = _read_file_text(Path(str(ctx.path)), path)
+ if text is None:
+ return _err(f"File could not be read: {path!r}")
+
+ from repowise.core.distill.budget import estimate_tokens
+
+ full_tokens = estimate_tokens(text)
+
+ if end < start:
+ start, end = end, start
+ requested_truncated = (end - start + 1) > _MAX_RANGE_LINES
+ if requested_truncated:
+ end = start + _MAX_RANGE_LINES - 1
+
+ # Cap the served span at _MAX_RANGE_LINES *including* context expansion —
+ # the docstring promises ≤200 lines, so context_lines must not push past
+ # it. Truncated reflects either an oversized request or a context-clipped
+ # span.
+ source, s, e, total = _slice_text(text, start, end, context_lines, max_lines=_MAX_RANGE_LINES)
+ range_truncated = requested_truncated or (e - s + 1) >= _MAX_RANGE_LINES
+
+ response = {
+ "symbol_id": symbol_id,
+ "file": path,
+ "kind": "range",
+ "start_line": s,
+ "end_line": e,
+ "total_lines": total,
+ "source": source,
+ "truncated": range_truncated,
+ "verified": True,
+ "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000, repository=repository),
+ }
+ from repowise.server.mcp_server._savings import declare_replaced
+
+ declare_replaced(response, full_tokens)
+ return response
+
+
+def _live_grep_fallback(repo_root: Path, file_path: str, name: str) -> list[dict]:
+ """Find ``name`` in the live file when the symbol index misses.
+
+ Turns a dead-end call (pure cost) into an answer: constants, imports,
+ aliases, and decorators live between indexed symbols, and the line that
+ defines them is usually all the agent needs. ±2 lines of context per
+ match, capped at _MAX_FALLBACK_MATCHES.
+ """
+ text = _read_file_text(repo_root, file_path)
+ if text is None:
+ return []
+ bare = _bare_name(name)
+ if not bare:
+ return []
+ lines = text.splitlines()
+ matches: list[dict] = []
+ for i, line in enumerate(lines, 1):
+ if bare in line:
+ lo, hi = max(1, i - 2), min(len(lines), i + 2)
+ matches.append({"line": i, "context": "\n".join(lines[lo - 1 : hi])})
+ if len(matches) >= _MAX_FALLBACK_MATCHES:
+ break
+ return matches
+
+
def _parse_symbol_id(symbol_id: str) -> tuple[str | None, str | None]:
"""Split a "{path}::{name}" id. Either side may be None if missing.
@@ -224,9 +333,7 @@ def _bare_name(name: str) -> str:
return tail
-def _pick_canonical(
- rows: list[WikiSymbol], queried_file_path: str | None
-) -> WikiSymbol | None:
+def _pick_canonical(rows: list[WikiSymbol], queried_file_path: str | None) -> WikiSymbol | None:
"""Deterministically select one row from a candidate list.
Priority:
@@ -243,7 +350,7 @@ def _pick_canonical(
rows = matching
# Deterministic: lowest id wins. (No confidence column today; leaving
# room to add one without changing the fallback.)
- rows_sorted = sorted(rows, key=lambda r: (r.id or ""))
+ rows_sorted = sorted(rows, key=lambda r: r.id or "")
if len(rows) > 1:
_log.warning(
"get_symbol: %d duplicate rows for lookup (file=%s); picked id=%s",
@@ -254,9 +361,7 @@ def _pick_canonical(
return rows_sorted[0]
-async def _resolve_symbol(
- session, repo_id: str, symbol_id: str
-) -> WikiSymbol | None:
+async def _resolve_symbol(session, repo_id: str, symbol_id: str) -> WikiSymbol | None:
"""Look up a symbol by id, qualified_name, or bare name. None if absent.
Language-agnostic: the qualified-name portion of the symbol_id is
@@ -324,19 +429,8 @@ async def _resolve_symbol(
return None
-def _slice_source(
- repo_path: Path, file_path: str, start_line: int, end_line: int, context_lines: int
-) -> tuple[str, int, int, int | None, int]:
- """Read the file and return (source, actual_start, actual_end, total_lines, full_tokens).
-
- ``full_tokens`` is the token cost of the *whole* file — the counterfactual
- a single-symbol slice replaces (the agent would have Read the file to find
- it). Returns ("", start, end, None, 0) on read failure. Lines are 1-indexed
- in the inputs and outputs to match WikiSymbol storage. Honors
- _MAX_SOURCE_LINES.
- """
- from repowise.core.distill.budget import estimate_tokens
-
+def _read_file_text(repo_path: Path, file_path: str) -> str | None:
+ """Read a repo file's live text, or None when unreadable/outside the root."""
abs_path = (repo_path / file_path).resolve()
# Defense in depth: never read outside the repo root, even if the
# WikiSymbol.file_path was somehow tampered with.
@@ -344,33 +438,42 @@ def _slice_source(
abs_path.relative_to(repo_path.resolve())
except ValueError:
_log.warning("get_symbol path escape attempt: %s", file_path)
- return "", start_line, end_line, None, 0
+ return None
try:
- text = abs_path.read_text(encoding="utf-8", errors="replace")
+ return abs_path.read_text(encoding="utf-8", errors="replace")
except OSError as exc:
_log.warning("get_symbol read failed for %s: %s", abs_path, exc)
- return "", start_line, end_line, None, 0
+ return None
- full_tokens = estimate_tokens(text)
+
+def _slice_text(
+ text: str,
+ start_line: int,
+ end_line: int,
+ context_lines: int,
+ max_lines: int = _MAX_SOURCE_LINES,
+) -> tuple[str, int, int, int]:
+ """Slice ``text`` to (source, actual_start, actual_end, total_lines).
+
+ Lines are 1-indexed inclusive to match WikiSymbol storage; the range is
+ expanded by ``context_lines`` on both sides and capped at ``max_lines``
+ (truncating from the tail — the head carries the signature, which is what
+ the agent needs to ground itself). The cap is applied AFTER context
+ expansion so the returned span never exceeds it.
+ """
lines = text.splitlines()
total = len(lines)
- # 1-indexed inclusive range, then expand by context_lines on both sides.
s = max(1, min(start_line, total))
e = max(s, min(end_line, total))
if context_lines > 0:
s = max(1, s - context_lines)
e = min(total, e + context_lines)
- span = e - s + 1
- if span > _MAX_SOURCE_LINES:
- # Truncate from the tail; the head usually has the signature
- # which is what the agent needs to ground itself.
- e = s + _MAX_SOURCE_LINES - 1
- span = _MAX_SOURCE_LINES
+ if (e - s + 1) > max_lines:
+ e = s + max_lines - 1
- sliced = "\n".join(lines[s - 1 : e])
- return sliced, s, e, total, full_tokens
+ return "\n".join(lines[s - 1 : e]), s, e, total
@mcp.tool()
@@ -380,25 +483,22 @@ async def get_symbol(
repo: str | None = None,
query: str | None = None,
) -> dict:
- """Read one function/class with exact line bounds — cheaper and safer than Read+math.
+ """Read one function/class/constant with live-verified line bounds.
- The only tool that returns the raw source bytes of a single indexed symbol
- without the agent having to compute offsets or guess at file structure.
- Bounded to ~400 lines (hard cap) so a misconfigured row can never blow up
- the context window. Pass the canonical ``"path/to/file.py::Name"`` that
- appears in ``get_context``'s symbol list. Also resolves omission refs:
- pass ``"repowise#<12-hex>"`` from a ``[repowise#...]`` truncation marker
- to retrieve the omitted content (``query`` filters it to matching lines).
-
- Returns {file, name, kind, signature, start_line, end_line, source,
- truncated}. On miss returns {error: "Symbol not found …"}.
+ Raw source of one indexed symbol, bounded (~400 lines) — cheaper than
+ Read+offset math. ``verified: true`` = bounds checked (or corrected)
+ against the live file: no follow-up Read needed. ``bounds:
+ "approximate"`` = the symbol moved and re-location failed. Also serves
+ live range reads ("path.py:140-180", ≤200 lines, always verified) and
+ omission refs ("repowise#<12-hex>"). Index misses grep the live file
+ and return fallback_lines instead of a dead end.
Args:
- symbol_id: "path/to/file.py::SymbolName" (canonical id from get_context),
- or "repowise#<12-hex>" from an omission marker.
- context_lines: extra source lines before/after (0-50, default 0).
+ symbol_id: "path/to/file.py::Name" (from get_context),
+ "path/to/file.py:140-180" for a live range, or an omission ref.
+ context_lines: extra lines before/after (0-50).
repo: usually omitted.
- query: omission refs only — regex (or substring) returning matching lines.
+ query: omission refs only — regex/substring filter on lines.
"""
if repo == "all":
return _unsupported_repo_all("get_symbol")
@@ -416,6 +516,20 @@ async def get_symbol(
if omission_ref is not None:
return _resolve_omission_ref(symbol_id, omission_ref, query, ctx.path, t0)
+ # Range read: "path/to/file.py:140-180" (single colon + numeric range —
+ # never collides with "{path}::{name}").
+ range_match = _RANGE_ID_RE.match(symbol_id.strip())
+ if range_match and "::" not in symbol_id:
+ return await _resolve_range_read(
+ symbol_id,
+ range_match.group("path"),
+ int(range_match.group("start")),
+ int(range_match.group("end")),
+ max(0, min(50, context_lines)),
+ ctx,
+ t0,
+ )
+
repository = None
if context_lines < 0 or context_lines > 50:
# Bound context_lines to a sane range — runaway values would
@@ -426,7 +540,33 @@ async def get_symbol(
repository = await _get_repo(session)
row = await _resolve_symbol(session, repository.id, symbol_id)
- if row is None or is_excluded(getattr(row, "file_path", None), _get_exclude_spec(ctx.path)):
+ exclude_spec = _get_exclude_spec(ctx.path)
+ if row is None or is_excluded(getattr(row, "file_path", None), exclude_spec):
+ # Dead-end recovery: constants/imports/aliases between indexed
+ # symbols miss the index but live in the file — grep the live file
+ # for the name and serve the matching lines instead of a pure error.
+ if row is None and ctx.path:
+ file_part, name_part = _parse_symbol_id(symbol_id)
+ if file_part and name_part and not is_excluded(file_part, exclude_spec):
+ matches = _live_grep_fallback(Path(str(ctx.path)), file_part, name_part)
+ if matches:
+ return {
+ "symbol_id": symbol_id,
+ "file": file_part,
+ "resolution": "live_grep",
+ "fallback_lines": matches,
+ "verified": True,
+ "note": (
+ "Not an indexed symbol, but the name matches these "
+ "live-file lines (likely a constant, import, or "
+ "alias). For surrounding source use a range read: "
+ f'"{file_part}:<start>-<end>".'
+ ),
+ "_meta": _build_meta(
+ timing_ms=(time.perf_counter() - t0) * 1000,
+ repository=repository,
+ ),
+ }
return {
"symbol_id": symbol_id,
"error": (
@@ -451,11 +591,9 @@ async def get_symbol(
}
repo_root = Path(str(ctx.path))
- source, start, end, _total, full_tokens = _slice_source(
- repo_root, row.file_path, row.start_line, row.end_line, context_lines
- )
+ text = _read_file_text(repo_root, row.file_path)
- if not source:
+ if text is None:
return {
"symbol_id": symbol_id,
"file": row.file_path,
@@ -472,8 +610,22 @@ async def get_symbol(
),
}
+ from repowise.core.distill.budget import estimate_tokens
+
+ full_tokens = estimate_tokens(text)
+
+ # Trust contract: verify the stored bounds against the live file before
+ # serving a single byte. Stale bounds get corrected via a one-file
+ # re-parse (and healed in the DB); un-relocatable symbols are served as
+ # the indexed guess, explicitly tagged approximate.
+ check = check_symbol_bounds(row, text)
+ if check.corrected:
+ await heal_symbol_row(ctx.session_factory, row, check.start_line, check.end_line)
+
+ source, start, end, _total = _slice_text(text, check.start_line, check.end_line, context_lines)
+
truncated = (end - start + 1) >= _MAX_SOURCE_LINES and (
- row.end_line - row.start_line + 1 + 2 * context_lines
+ check.end_line - check.start_line + 1 + 2 * context_lines
) > _MAX_SOURCE_LINES
response = {
@@ -486,16 +638,26 @@ async def get_symbol(
"language": row.language,
"start_line": start,
"end_line": end,
- "symbol_start_line": row.start_line,
- "symbol_end_line": row.end_line,
+ "symbol_start_line": check.start_line,
+ "symbol_end_line": check.end_line,
"source": source,
"truncated": truncated,
+ "verified": check.verified,
"_meta": _build_meta(
timing_ms=(time.perf_counter() - t0) * 1000,
- hint=_symbol_hint(row.symbol_id, row.end_line, row.start_line),
+ hint=_symbol_hint(row.symbol_id, check.end_line, check.start_line),
repository=repository,
),
}
+ if check.approximate:
+ response["bounds"] = "approximate"
+ response["note"] = (
+ "The live file no longer contains this symbol at its indexed "
+ "location and it could not be re-located by name — it may have "
+ "been renamed or removed since indexing. The served slice is "
+ "the indexed line range from the current file contents; verify "
+ "before citing."
+ )
# Declare the exact counterfactual: serving one symbol replaced Reading the
# whole file. The savings instrumentation prefers this over its estimator.
from repowise.server.mcp_server._savings import declare_replaced
diff --git a/packages/server/src/repowise/server/mcp_server/tool_why.py b/packages/server/src/repowise/server/mcp_server/tool_why.py
index 49850e5af..7dc9bd49e 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_why.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_why.py
@@ -38,29 +38,18 @@ async def get_why(
targets: list[str] | None = None,
repo: str | None = None,
) -> dict:
- """Why this code looks the way it does — decision archaeology git log cannot answer.
+ """Why this code is shaped this way — decision records + evidence commits.
- The only tool that surfaces architectural decision records, their status
- (active / proposed / deprecated / superseded), and the commits that are
- evidence for them. ``git log`` tells you *what* changed; this tells you
- *why we chose this design* — call it before any architectural change,
- refactor of an owned module, or pattern divergence in a community.
-
- Four modes:
- 1. ``get_why("why is auth using JWT?")`` — keyword + semantic decision search.
- 2. ``get_why("src/auth/service.py")`` — decisions governing the file plus
- origin story and an alignment score (does this file follow its own ADRs?).
- 3. ``get_why("why was caching added?", targets=["src/auth/cache.py"])`` —
- target-anchored search; decisions touching the targets get boosted.
- 4. ``get_why()`` — health dashboard (stale, proposed, ungoverned hotspots).
-
- When no decisions exist for a path, falls back to git archaeology
- (significant commits + cross-file references) so the call is never empty.
+ Call before refactors or pattern divergences. Query modes: a question
+ ("why is auth using JWT?"), a file path (governing decisions + origin
+ story + alignment score), a question anchored to targets, or no query
+ (decision health dashboard). Falls back to git archaeology when no
+ decisions exist for a path — never empty.
Args:
- query: Natural language question, file/module path, or omit for health dashboard.
- targets: Optional file paths to anchor the search.
- repo: Repository path, name, or ID.
+ query: question, file/module path, or omit for the dashboard.
+ targets: optional file paths to anchor the search.
+ repo: usually omitted.
"""
# --- repo="all": search decisions across ALL repos ---
if repo == "all":
diff --git a/tests/unit/ingestion/parser/test_commonjs_require.py b/tests/unit/ingestion/parser/test_commonjs_require.py
index a520d4a64..cd9bcf68d 100644
--- a/tests/unit/ingestion/parser/test_commonjs_require.py
+++ b/tests/unit/ingestion/parser/test_commonjs_require.py
@@ -110,3 +110,20 @@ def test_member_pick_require_is_extracted(parser: ASTParser) -> None:
# pattern never matched it.
result = _parse(parser, "var normalizeType = require('./utils').normalizeType;\n")
assert any(i.module_path == "./utils" for i in result.imports)
+
+
+def test_top_level_js_constants_extracted_but_requires_are_not(parser: ASTParser) -> None:
+ result = _parse(
+ parser,
+ "const svc = require('./svc');\n"
+ "const TIMEOUT_MS = 5000;\n"
+ "let counter = 0;\n"
+ "function h() { const local = 1; return local; }\n",
+ )
+ by_name = {s.name: s for s in result.symbols}
+ assert by_name["TIMEOUT_MS"].kind == "constant"
+ assert by_name["TIMEOUT_MS"].signature == "TIMEOUT_MS = 5000"
+ assert by_name["counter"].kind == "variable"
+ # require() declarators are imports, not symbols
+ assert "svc" not in by_name
+ assert "local" not in by_name
diff --git a/tests/unit/ingestion/parser/test_python.py b/tests/unit/ingestion/parser/test_python.py
index 22fb3b58d..12406a468 100644
--- a/tests/unit/ingestion/parser/test_python.py
+++ b/tests/unit/ingestion/parser/test_python.py
@@ -232,3 +232,83 @@ class TestPythonParser:
# Public top-level symbols should be in exports
assert "add" in result.exports
assert "Calculator" in result.exports
+
+
+PYTHON_CONSTANTS_SOURCE = b'''"""Module with constants."""
+
+import os
+
+_DEFAULT_CO_CHANGE_MIN_COUNT = 2
+MAX_RETRIES: int = 5
+app = create_app()
+_TABLE = {
+ "a": 1,
+}
+
+
+def f(x):
+ local_var = 3
+ return x
+
+
+class C:
+ class_attr = 7
+
+ def m(self):
+ inner = 1
+ return inner
+'''
+
+
+class TestPythonModuleConstants:
+ """Module-level assignments are indexed as constant/variable symbols."""
+
+ def _symbols(self, parser: ASTParser):
+ fi = _make_file_info("pkg/consts.py", "python")
+ return parser.parse_file(fi, PYTHON_CONSTANTS_SOURCE).symbols
+
+ def test_screaming_case_assignment_is_constant(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ const = next(s for s in syms if s.name == "_DEFAULT_CO_CHANGE_MIN_COUNT")
+ assert const.kind == "constant"
+ assert const.signature == "_DEFAULT_CO_CHANGE_MIN_COUNT = 2"
+
+ def test_typed_assignment_keeps_annotation_in_signature(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ const = next(s for s in syms if s.name == "MAX_RETRIES")
+ assert const.kind == "constant"
+ assert const.signature == "MAX_RETRIES: int = 5"
+
+ def test_lowercase_assignment_is_variable(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ var = next(s for s in syms if s.name == "app")
+ assert var.kind == "variable"
+ assert var.signature == "app = create_app()"
+
+ def test_multiline_value_signature_is_first_line(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ table = next(s for s in syms if s.name == "_TABLE")
+ assert table.kind == "constant"
+ assert table.signature == "_TABLE = {"
+ assert table.end_line > table.start_line
+
+ def test_function_local_assignment_not_extracted(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ assert not any(s.name == "local_var" for s in syms)
+ assert not any(s.name == "inner" for s in syms)
+
+ def test_class_attribute_not_extracted(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ assert not any(s.name == "class_attr" for s in syms)
+
+ def test_no_letter_names_are_variables_not_constants(self, parser: ASTParser) -> None:
+ # ``__all__`` and ``_`` have no cased letters; ``name == name.upper()``
+ # would mislabel them constants. ``str.isupper()`` correctly yields
+ # variable.
+ src = b'__all__ = ["a"]\n_ = compute()\nDunder = 1\n'
+ fi = _make_file_info("pkg/dunder.py", "python")
+ syms = parser.parse_file(fi, src).symbols
+ assert next(s for s in syms if s.name == "__all__").kind == "variable"
+ assert next(s for s in syms if s.name == "_").kind == "variable"
+ # Mixed-case still resolves to variable (only SCREAMING_CASE is const).
+ assert next(s for s in syms if s.name == "Dunder").kind == "variable"
diff --git a/tests/unit/ingestion/parser/test_typescript.py b/tests/unit/ingestion/parser/test_typescript.py
index c62955d74..3a7eb8208 100644
--- a/tests/unit/ingestion/parser/test_typescript.py
+++ b/tests/unit/ingestion/parser/test_typescript.py
@@ -219,3 +219,56 @@ def test_cts_file_uses_typescript_parser(parser: ASTParser) -> None:
fi = _make_file_info("src/module.cts", "typescript")
parsed = parser.parse_file(fi, b"export function load(): number { return 1; }\n")
assert any(s.name == "load" for s in parsed.symbols)
+
+
+class TestTypeScriptModuleConstants:
+ """Top-level const/let with literal values are indexed as constants."""
+
+ TS_CONST_SOURCE = b"""
+import { x } from "./x";
+export const MAX_ITEMS = 100;
+const apiBase = "https://api.example.com";
+export const CONFIG = {
+ retries: 3,
+};
+export const handler = () => {
+ const inner = 1;
+ return inner;
+};
+function g() {
+ const localConst = 2;
+ return localConst;
+}
+"""
+
+ def _symbols(self, parser: ASTParser):
+ fi = _make_file_info("pkg/consts.ts", "typescript")
+ return parser.parse_file(fi, self.TS_CONST_SOURCE).symbols
+
+ def test_exported_screaming_const_is_constant(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ const = next(s for s in syms if s.name == "MAX_ITEMS")
+ assert const.kind == "constant"
+ assert const.signature == "MAX_ITEMS = 100"
+
+ def test_camel_case_const_is_variable(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ var = next(s for s in syms if s.name == "apiBase")
+ assert var.kind == "variable"
+
+ def test_object_const_signature_is_first_line(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ config = next(s for s in syms if s.name == "CONFIG")
+ assert config.kind == "constant"
+ assert config.signature == "CONFIG = {"
+
+ def test_arrow_function_const_stays_function(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ handler = next(s for s in syms if s.name == "handler")
+ assert handler.kind == "function"
+
+ def test_function_local_const_not_extracted(self, parser: ASTParser) -> None:
+ syms = self._symbols(parser)
+ names = {s.name for s in syms}
+ assert "localConst" not in names
+ assert "inner" not in names
diff --git a/tests/unit/server/mcp/test_answer_cache.py b/tests/unit/server/mcp/test_answer_cache.py
new file mode 100644
index 000000000..f95c1acb1
--- /dev/null
+++ b/tests/unit/server/mcp/test_answer_cache.py
@@ -0,0 +1,193 @@
+"""Answer-cache lifecycle: upsert on re-synthesis, commit/TTL invalidation.
+
+Regression coverage for the silent-failure mode where the cache write was a
+plain INSERT under ``suppress(Exception)``: every bypass-and-resynthesize
+round (hedged rows, schema bumps) violated ``uq_answer_cache_q`` and failed
+silently, so a bad cached row was permanent. The write is now a
+delete-then-insert upsert, and reads invalidate on indexed-commit change or
+hard TTL.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from datetime import UTC, datetime, timedelta
+from types import SimpleNamespace
+
+import pytest
+from sqlalchemy import select
+
+from repowise.core.persistence.models import AnswerCache, Repository
+
+QUESTION = "how does the auth service work"
+
+# Top score >= 3.0 with an absolute gap >= 0.5 → dominant → synthesis runs.
+_HITS = [
+ {"page_id": "file_page:src/auth/service.py", "score": 5.0},
+ {"page_id": "file_page:src/auth/middleware.py", "score": 4.0},
+]
+
+
+def _patch_retrieval(monkeypatch, answer_mod):
+ async def _fake_retrieve(question, ctx):
+ return [dict(h) for h in _HITS]
+
+ async def _fake_hydrate(hits, ctx, *, scope=None):
+ for h in hits:
+ h["target_path"] = h["page_id"].removeprefix("file_page:")
+ h["title"] = h["target_path"]
+ h["summary"] = ""
+ h["snippet"] = ""
+ h["page_type"] = "file_page"
+ return hits
+
+ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)
+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)
+
+
+class _Provider:
+ provider_name = "mock"
+ model_name = "mock-1"
+
+ def __init__(self, content: str) -> None:
+ self.content = content
+ self.calls = 0
+
+ async def generate(self, **kwargs):
+ self.calls += 1
+ return SimpleNamespace(content=self.content)
+
+
+def _patch_provider(monkeypatch, answer_mod, provider: _Provider) -> None:
+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: provider)
+
+
+async def _cache_rows(factory) -> list[AnswerCache]:
+ from repowise.core.persistence.database import get_session
+
+ async with get_session(factory) as session:
+ res = await session.execute(select(AnswerCache))
+ return list(res.scalars().all())
+
+
+async def test_hedged_row_is_upgraded_on_resynthesis(setup_mcp, factory, monkeypatch):
+ """Hedged cached answer → bypass → re-synthesis → row UPGRADED, not orphaned."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_retrieval(monkeypatch, answer_mod)
+
+ hedged = _Provider("The provided excerpts do not contain the implementation details.")
+ _patch_provider(monkeypatch, answer_mod, hedged)
+ first = await get_answer(QUESTION)
+ assert first["confidence"] == "low"
+
+ rows = await _cache_rows(factory)
+ assert len(rows) == 1
+ assert "do not contain" in _json.loads(rows[0].payload_json)["answer"]
+
+ direct = _Provider("Auth flows through src/auth/service.py via AuthService.check().")
+ _patch_provider(monkeypatch, answer_mod, direct)
+ second = await get_answer(QUESTION)
+ assert direct.calls == 1, "hedged cache entry must be bypassed, not returned"
+ assert "AuthService.check" in second["answer"]
+
+ rows = await _cache_rows(factory)
+ assert len(rows) == 1, "upsert must replace the hedged row, not duplicate or fail"
+ upgraded = _json.loads(rows[0].payload_json)
+ assert "AuthService.check" in upgraded["answer"], "row must carry the upgraded answer"
+
+ # Third call: the upgraded row is a normal cache hit — no synthesis.
+ third = await get_answer(QUESTION)
+ assert direct.calls == 1, "upgraded row must serve from cache"
+ assert third["_meta"].get("cached") is True
+ assert "_indexed_commit" not in third
+
+
+async def test_cache_bypassed_when_indexed_commit_changes(setup_mcp, factory, session, monkeypatch):
+ """A row stamped at commit A is bypassed once the repo is indexed at B."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_retrieval(monkeypatch, answer_mod)
+
+ repo = (await session.execute(select(Repository))).scalars().first()
+ repo.head_commit = "a" * 40
+ await session.commit()
+
+ v1 = _Provider("Answer synthesised at commit A (src/auth/service.py).")
+ _patch_provider(monkeypatch, answer_mod, v1)
+ await get_answer(QUESTION)
+ assert v1.calls == 1
+
+ # Same commit → cache hit, no new synthesis.
+ await get_answer(QUESTION)
+ assert v1.calls == 1
+
+ repo.head_commit = "b" * 40
+ await session.commit()
+
+ v2 = _Provider("Answer synthesised at commit B (src/auth/service.py).")
+ _patch_provider(monkeypatch, answer_mod, v2)
+ result = await get_answer(QUESTION)
+ assert v2.calls == 1, "commit change must bypass the cached row"
+ assert "commit B" in result["answer"]
+
+ rows = await _cache_rows(factory)
+ assert len(rows) == 1
+ assert _json.loads(rows[0].payload_json)["_indexed_commit"] == "b" * 40
+
+
+async def test_cache_row_past_ttl_is_bypassed(setup_mcp, factory, session, monkeypatch):
+ """Rows older than the hard TTL re-synthesise even without commit metadata."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_retrieval(monkeypatch, answer_mod)
+
+ v1 = _Provider("Original answer (src/auth/service.py).")
+ _patch_provider(monkeypatch, answer_mod, v1)
+ await get_answer(QUESTION)
+
+ rows = await _cache_rows(factory)
+ assert len(rows) == 1
+ from repowise.core.persistence.database import get_session
+
+ async with get_session(factory) as s:
+ row = (await s.execute(select(AnswerCache))).scalars().one()
+ row.created_at = datetime.now(UTC) - timedelta(days=30)
+ await s.commit()
+
+ v2 = _Provider("Fresh answer (src/auth/service.py).")
+ _patch_provider(monkeypatch, answer_mod, v2)
+ result = await get_answer(QUESTION)
+ assert v2.calls == 1, "expired row must be bypassed"
+ assert "Fresh answer" in result["answer"]
+
+
+async def test_cache_write_failure_logs_instead_of_silencing(setup_mcp, monkeypatch, caplog):
+ """A failing cache write must not block the response — and must be logged."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_retrieval(monkeypatch, answer_mod)
+ _patch_provider(monkeypatch, answer_mod, _Provider("Answer text (src/auth/service.py)."))
+
+ real_dumps = answer_mod._json.dumps
+
+ def _boom(obj, *a, **k):
+ if isinstance(obj, dict) and "_schema_version" in obj:
+ raise RuntimeError("simulated serialization failure")
+ return real_dumps(obj, *a, **k)
+
+ monkeypatch.setattr(answer_mod._json, "dumps", _boom)
+
+ with caplog.at_level("WARNING", logger="repowise.mcp.answer"):
+ result = await get_answer(QUESTION)
+
+ assert result["answer"], "response must survive a cache-write failure"
+ assert any("cache write failed" in r.message for r in caplog.records)
diff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.py
new file mode 100644
index 000000000..e36341622
--- /dev/null
+++ b/tests/unit/server/mcp/test_answer_calibration.py
@@ -0,0 +1,281 @@
+"""Confidence calibration gates for get_answer.
+
+Covers the three A-series gates that ground confidence in answer *content*
+rather than retrieval scores alone:
+
+ * expanded hedge markers ("do not include", "can't enumerate", …)
+ * value-grounding gate — numbers asserted on value-shaped questions must
+ appear in the retrieved material, else confidence caps at low
+ * citation-source gate — high confidence requires ≥1 cited page that
+ contributed actual source (hydrated symbols), not just summaries
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.server.mcp_server.tool_answer.confidence import (
+ _answer_is_hedged,
+ _is_value_question,
+ _ungrounded_numbers,
+)
+
+# ---------------------------------------------------------------------------
+# Pure-predicate unit tests
+# ---------------------------------------------------------------------------
+
+
+class TestHedgeMarkers:
+ def test_do_not_include_detected(self) -> None:
+ assert _answer_is_hedged("The provided wiki excerpts do not include the source body.")
+
+ def test_cannot_enumerate_detected(self) -> None:
+ assert _answer_is_hedged("I can't enumerate the exact callers from the excerpts.")
+
+ def test_unable_to_determine_detected(self) -> None:
+ assert _answer_is_hedged("The exact default is unable to determine from this material.")
+
+ def test_marker_late_in_answer_detected(self) -> None:
+ long_preamble = "The module handles ingestion. " * 40
+ assert _answer_is_hedged(long_preamble + "However, the excerpts do not include the value.")
+
+ def test_direct_answer_not_hedged(self) -> None:
+ assert not _answer_is_hedged("The default is 2, set in git_indexer/_constants.py.")
+
+
+class TestValueQuestionShape:
+ def test_default_question_is_value_shaped(self) -> None:
+ assert _is_value_question("What is the default value of _MIN_COUNT?")
+
+ def test_threshold_question_is_value_shaped(self) -> None:
+ assert _is_value_question("what threshold gates the dominance ratio")
+
+ def test_how_many_is_value_shaped(self) -> None:
+ assert _is_value_question("How many retrieval hits are returned?")
+
+ def test_mechanism_question_is_not(self) -> None:
+ assert not _is_value_question("How does the ingestion pipeline parse imports?")
+
+
+class TestUngroundedNumbers:
+ HITS = [
+ {
+ "title": "constants",
+ "summary": "Co-change tuning constants.",
+ "snippet": "",
+ "symbols": [
+ {
+ "name": "_DEFAULT_CO_CHANGE_MIN_COUNT",
+ "signature": "_DEFAULT_CO_CHANGE_MIN_COUNT = 2",
+ "docstring": "",
+ }
+ ],
+ }
+ ]
+
+ def test_invented_number_is_ungrounded(self) -> None:
+ assert _ungrounded_numbers("The default minimum count is 3.", self.HITS) == ["3"]
+
+ def test_number_present_in_signature_is_grounded(self) -> None:
+ assert _ungrounded_numbers("The default minimum count is 2.", self.HITS) == []
+
+ def test_file_line_citations_are_not_value_assertions(self) -> None:
+ text = "The default is 2 (git_indexer/_constants.py:114)."
+ assert _ungrounded_numbers(text, self.HITS) == []
+
+ def test_no_numbers_in_answer_is_grounded(self) -> None:
+ assert _ungrounded_numbers("It reads the tuning constant from config.", self.HITS) == []
+
+ def test_underscore_separated_constant_is_grounded(self) -> None:
+ # Source ``MAX = 100_000`` and an answer that says "100000" are the
+ # same value — the digit-separator strip must keep this grounded.
+ hits = [{"symbols": [{"name": "MAX", "signature": "MAX = 100_000", "docstring": ""}]}]
+ assert _ungrounded_numbers("The cap is 100000 tokens.", hits) == []
+
+ def test_comma_grouped_answer_is_grounded(self) -> None:
+ # Prose commas (``100,000``) must not split into 100 and 000 and read
+ # as ungrounded against ``100_000`` in source.
+ hits = [{"symbols": [{"name": "MAX", "signature": "MAX = 100_000", "docstring": ""}]}]
+ assert _ungrounded_numbers("The cap is 100,000 tokens.", hits) == []
+
+
+# ---------------------------------------------------------------------------
+# End-to-end gate behaviour through get_answer
+# ---------------------------------------------------------------------------
+
+_SYMBOL = {
+ "name": "MIN_COUNT",
+ "kind": "constant",
+ "signature": "MIN_COUNT = 2",
+ "docstring": "",
+ "start_line": 10,
+ "end_line": 10,
+ "_matched": True,
+}
+
+# Function-kind variant: matched, but not extractable by the C1 fast path —
+# used by tests that must reach the synthesis gates on value questions.
+_FN_SYMBOL = {
+ "name": "min_count_policy",
+ "kind": "function",
+ "signature": "def min_count_policy() -> int",
+ "docstring": "Returns the default minimum count, 2.",
+ "start_line": 10,
+ "end_line": 14,
+ "_matched": True,
+}
+
+
+def _patch_pipeline(monkeypatch, answer_mod, *, with_symbols: bool, symbol: dict | None = None):
+ async def _fake_retrieve(question, ctx):
+ return [
+ {"page_id": "file_page:pkg/alpha/one.py", "score": 5.0},
+ {"page_id": "file_page:pkg/alpha/two.py", "score": 4.0},
+ ]
+
+ async def _fake_hydrate(hits, ctx, *, scope=None):
+ for i, h in enumerate(hits):
+ h["target_path"] = h["page_id"].removeprefix("file_page:")
+ h["title"] = h["target_path"]
+ h["summary"] = "Auth service summary."
+ h["snippet"] = ""
+ h["page_type"] = "file_page"
+ if with_symbols and i == 0:
+ h["symbols"] = [dict(symbol or _SYMBOL)]
+ return hits
+
+ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)
+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)
+
+
+def _patch_provider(monkeypatch, answer_mod, content: str):
+ class _Provider:
+ provider_name = "mock"
+ model_name = "mock-1"
+
+ async def generate(self, **kwargs):
+ return SimpleNamespace(content=content)
+
+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: _Provider())
+
+
+async def test_ungrounded_value_caps_confidence_low(setup_mcp, monkeypatch):
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True, symbol=_FN_SYMBOL)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The default of min_count_policy is 3 (pkg/alpha/one.py).",
+ )
+
+ result = await get_answer("What is the default value of min_count_policy?")
+ assert result["confidence"] == "low"
+ assert "3" in result["note"]
+ assert "next_action_hint" in result
+
+
+async def test_grounded_value_keeps_high_confidence(setup_mcp, monkeypatch):
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True, symbol=_FN_SYMBOL)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The default of min_count_policy is 2 (pkg/alpha/one.py).",
+ )
+
+ result = await get_answer("What is the default value of min_count_policy?")
+ assert result["confidence"] == "high"
+ assert "High confidence" in result["note"]
+
+
+async def test_high_confidence_requires_source_backed_citation(setup_mcp, monkeypatch):
+ """No cited page contributed symbols → high is downgraded to medium."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=False)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "Auth flows through middleware into the service (pkg/alpha/one.py).",
+ )
+
+ result = await get_answer("how does the auth flow work end to end")
+ assert result["confidence"] == "medium"
+
+
+async def test_expanded_hedge_marker_downgrades_through_pipeline(setup_mcp, monkeypatch):
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True, symbol=_FN_SYMBOL)
+ _patch_provider(
+ monkeypatch,
+ answer_mod,
+ "The provided excerpts do not include the body of min_count_policy.",
+ )
+
+ result = await get_answer("What is the default value of min_count_policy?")
+ assert result["confidence"] == "low"
+ assert result["retrieval"] == []
+
+
+async def test_value_question_uses_extraction_fast_path(setup_mcp, monkeypatch):
+ """C1: matched constant + value question → verbatim line, no LLM call."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)
+
+ def _no_provider(_p):
+ raise AssertionError("fast path must not resolve a provider")
+
+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", _no_provider)
+
+ result = await get_answer("What is the default value of MIN_COUNT?")
+ assert result["grounding"] == "extracted"
+ assert result["confidence"] == "high"
+ assert "MIN_COUNT = 2" in result["answer"]
+ assert "pkg/alpha/one.py:10" in result["answer"]
+ assert result["citations"] == ["pkg/alpha/one.py"]
+ assert result["retrieval"] == []
+
+
+async def test_mechanism_question_skips_fast_path(setup_mcp, monkeypatch):
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)
+ _patch_provider(monkeypatch, answer_mod, "MIN_COUNT gates retries (pkg/alpha/one.py).")
+
+ result = await get_answer("How does MIN_COUNT influence the retry loop?")
+ assert "grounding" not in result
+
+
+async def test_synthesized_answer_carries_grounded_quotes(setup_mcp, monkeypatch):
+ """C2: symbols named in the answer attach {path, lines, quote}."""
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, with_symbols=True)
+ _patch_provider(monkeypatch, answer_mod, "Retries are gated by MIN_COUNT (pkg/alpha/one.py).")
+
+ result = await get_answer("How does the retry gating mechanism work here?")
+ assert result.get("quotes"), "answer naming MIN_COUNT must carry a quote"
+ [q] = result["quotes"]
+ assert q["path"] == "pkg/alpha/one.py"
+ assert q["lines"][0] == 10
+ assert "MIN_COUNT = 2" in q["quote"]
diff --git a/tests/unit/server/mcp/test_answer_payload.py b/tests/unit/server/mcp/test_answer_payload.py
new file mode 100644
index 000000000..cd003f280
--- /dev/null
+++ b/tests/unit/server/mcp/test_answer_payload.py
@@ -0,0 +1,194 @@
+"""Payload diet for get_answer (B1/B2).
+
+* serialize_hits strips internal scoring fields — zero plumbing reaches
+ the agent (path/title/summary/snippet/excerpt/score/key_symbols only)
+* the retrieval block is confidence-conditional: high → none, medium →
+ top-2 truncated, low/gated → full serialized block
+* regression guard: no response key may start with "_" except _meta
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from repowise.server.mcp_server.tool_answer.retrieval import serialize_hits
+
+# ---------------------------------------------------------------------------
+# serialize_hits unit tests
+# ---------------------------------------------------------------------------
+
+RAW_HIT = {
+ "page_id": "file_page:pkg/mod.py",
+ "target_path": "pkg/mod.py",
+ "title": "mod",
+ "summary": "A module that does things. " * 20,
+ "snippet": "def f(): ...",
+ "score": 4.321987,
+ "_coverage": 0.4,
+ "_raw_score": 3.9,
+ "_intersection": True,
+ "_pagerank": 0.002,
+ "_pagerank_bias": 1.01,
+ "_sources": {"fts", "vector"},
+ "_domain_penalty": None,
+ "symbols": [
+ {"name": "f", "kind": "function", "signature": "def f()", "_matched": True},
+ ],
+}
+
+
+class TestSerializeHits:
+ def test_internal_fields_stripped(self) -> None:
+ [entry] = serialize_hits([dict(RAW_HIT)])
+ assert not [k for k in entry if k.startswith("_")]
+ assert "page_id" not in entry
+ assert entry["path"] == "pkg/mod.py"
+ assert entry["score"] == 4.322
+
+ def test_symbol_internal_fields_stripped(self) -> None:
+ [entry] = serialize_hits([dict(RAW_HIT)])
+ [sym] = entry["key_symbols"]
+ assert "_matched" not in sym
+ assert sym["signature"] == "def f()"
+
+ def test_summary_truncation(self) -> None:
+ [entry] = serialize_hits([dict(RAW_HIT)], summary_chars=160)
+ assert len(entry["summary"]) <= 160
+
+ def test_limit(self) -> None:
+ hits = [dict(RAW_HIT), dict(RAW_HIT), dict(RAW_HIT)]
+ assert len(serialize_hits(hits, limit=2)) == 2
+
+ def test_graph_expanded_hit_loses_symbols_when_asked(self) -> None:
+ expanded = dict(RAW_HIT, _sources={"graph_expand"})
+ [entry] = serialize_hits([expanded], symbols_for_expanded=False)
+ assert "key_symbols" not in entry
+ [kept] = serialize_hits([expanded], symbols_for_expanded=True)
+ assert "key_symbols" in kept
+
+
+# ---------------------------------------------------------------------------
+# Confidence-conditional retrieval through get_answer
+# ---------------------------------------------------------------------------
+
+
+def _assert_no_underscore_keys(obj, path="root"):
+ if isinstance(obj, dict):
+ for k, v in obj.items():
+ assert not (str(k).startswith("_") and k != "_meta"), (
+ f"internal key {k!r} leaked at {path}"
+ )
+ if k != "_meta":
+ _assert_no_underscore_keys(v, f"{path}.{k}")
+ elif isinstance(obj, list):
+ for i, v in enumerate(obj):
+ _assert_no_underscore_keys(v, f"{path}[{i}]")
+
+
+def _patch_pipeline(monkeypatch, answer_mod, scores=(5.0, 4.0)):
+ async def _fake_retrieve(question, ctx):
+ return [
+ {"page_id": "file_page:pkg/beta/one.py", "score": scores[0], "_sources": {"fts"}},
+ {"page_id": "file_page:pkg/beta/two.py", "score": scores[1], "_sources": {"fts"}},
+ ]
+
+ async def _fake_hydrate(hits, ctx, *, scope=None):
+ for i, h in enumerate(hits):
+ h["target_path"] = h["page_id"].removeprefix("file_page:")
+ h["title"] = h["target_path"]
+ h["summary"] = "Summary text for the page. " * 12
+ h["snippet"] = ""
+ h["page_type"] = "file_page"
+ if i == 0:
+ h["symbols"] = [
+ {
+ "name": "go",
+ "kind": "function",
+ "signature": "def go()",
+ "docstring": "",
+ "start_line": 3,
+ "end_line": 9,
+ "_matched": True,
+ }
+ ]
+ return hits
+
+ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)
+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)
+
+
+def _patch_provider(monkeypatch, answer_mod, content):
+ class _Provider:
+ provider_name = "mock"
+ model_name = "mock-1"
+
+ async def generate(self, **kwargs):
+ return SimpleNamespace(content=content)
+
+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: _Provider())
+
+
+async def test_high_confidence_drops_retrieval_block(setup_mcp, monkeypatch):
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, scores=(5.0, 4.0))
+ _patch_provider(monkeypatch, answer_mod, "The go() function drives it (pkg/beta/one.py).")
+
+ result = await get_answer("how does the beta module go function work")
+ assert result["confidence"] == "high"
+ assert result["retrieval"] == []
+ assert result["fallback_targets"], "routing targets survive the diet"
+ _assert_no_underscore_keys(result)
+
+
+async def test_medium_confidence_keeps_two_truncated_hits(setup_mcp, monkeypatch):
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ # ratio 1.27 >= 1.2 but top score < 1.5 floor → medium.
+ _patch_pipeline(monkeypatch, answer_mod, scores=(1.4, 1.1))
+ _patch_provider(monkeypatch, answer_mod, "The go() function drives it (pkg/beta/one.py).")
+
+ result = await get_answer("how does the beta module go function work")
+ assert result["confidence"] == "medium"
+ assert 0 < len(result["retrieval"]) <= 2
+ for entry in result["retrieval"]:
+ assert len(entry.get("summary", "")) <= 160
+ _assert_no_underscore_keys(result)
+
+
+async def test_gated_path_serves_clean_retrieval(setup_mcp, monkeypatch):
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ # 2.0 vs 1.9: top < 3.0 and ratio 1.05 < 1.2 → gated, no synthesis.
+ _patch_pipeline(monkeypatch, answer_mod, scores=(2.0, 1.9))
+ _patch_provider(monkeypatch, answer_mod, "unused")
+
+ result = await get_answer("how does the beta module go function work")
+ assert result["confidence"] == "low"
+ assert result["best_guesses"]
+ for entry in result["retrieval"]:
+ assert "page_id" not in entry
+ assert entry.get("path")
+ _assert_no_underscore_keys(result)
+
+
+async def test_cached_response_carries_no_internal_keys(setup_mcp, monkeypatch):
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.server.mcp_server import get_answer
+
+ _patch_pipeline(monkeypatch, answer_mod, scores=(5.0, 4.0))
+ _patch_provider(monkeypatch, answer_mod, "The go() function drives it (pkg/beta/one.py).")
+
+ await get_answer("how does the beta module go function work")
+ cached = await get_answer("how does the beta module go function work")
+ assert cached["_meta"].get("cached") is True
+ _assert_no_underscore_keys(cached)
diff --git a/tests/unit/server/mcp/test_context.py b/tests/unit/server/mcp/test_context.py
index 54694f636..68e9ccc5e 100644
--- a/tests/unit/server/mcp/test_context.py
+++ b/tests/unit/server/mcp/test_context.py
@@ -452,3 +452,18 @@ async def test_batch_isolation_one_target_errors(setup_mcp, monkeypatch):
assert "boom" in targets
assert "error" in targets["boom"]
assert targets["boom"]["target"] == "boom"
+
+
+async def test_file_target_callers_rolls_up_importers(setup_mcp):
+ """B5: include=["callers"] on a FILE target returns the import rollup
+ instead of an empty list (which forced a second round-trip)."""
+ from repowise.server.mcp_server import get_context
+
+ result = await get_context(["src/auth/service.py"], include=["callers"], compact=False)
+ t = result["targets"]["src/auth/service.py"]
+ callers = t.get("callers")
+ assert callers, "file-level callers must not be empty when importers exist"
+ [middleware] = [c for c in callers if c["file"] == "src/auth/middleware.py"]
+ assert middleware.get("imports") is True
+ assert "rollup" in t.get("_call_graph_note", "")
diff --git a/tests/unit/server/mcp/test_counterfactual.py b/tests/unit/server/mcp/test_counterfactual.py
index 5cfd68543..600fa6f1a 100644
--- a/tests/unit/server/mcp/test_counterfactual.py
+++ b/tests/unit/server/mcp/test_counterfactual.py
@@ -42,7 +42,7 @@ def test_search_codebase_no_results_returns_zero() -> None:
def test_unknown_tool_returns_zero() -> None:
- assert cf.replaced_tokens_for("get_risk", {"anything": 1}) == 0
+ assert cf.replaced_tokens_for("list_repos", {"anything": 1}) == 0
def test_non_dict_result_returns_zero() -> None:
@@ -59,3 +59,56 @@ def test_malformed_skeleton_does_not_raise() -> None:
}
}
assert cf.replaced_tokens_for("get_context", result) == 0
+
+
+def test_get_answer_counts_search_plus_cited_reads() -> None:
+ result = {
+ "answer": "The default is 2 (pkg/a.py).",
+ "citations": ["pkg/a.py"],
+ "fallback_targets": ["pkg/a.py", "pkg/b.py"],
+ }
+ expected = cf.ANSWER_SEARCH_FLOOR + 2 * cf.ANSWER_READ_FLOOR_PER_FILE
+ assert cf.replaced_tokens_for("get_answer", result) == expected
+
+
+def test_get_answer_empty_answer_claims_nothing() -> None:
+ # Gated/low responses tell the agent to go read — those reads still
+ # happen, so claiming them as saved repeats the E11 miscalibration.
+ result = {"answer": "", "best_guesses": [{"file": "pkg/a.py"}]}
+ assert cf.replaced_tokens_for("get_answer", result) == 0
+
+
+def test_fixed_floor_tools_credit_successful_calls_only() -> None:
+ assert cf.replaced_tokens_for("get_risk", {"targets": ["a.py"]}) == cf.RISK_FLOOR
+ assert cf.replaced_tokens_for("get_risk", {"error": "nope"}) == 0
+ assert cf.replaced_tokens_for("get_why", {"decisions": []}) == cf.WHY_FLOOR
+ assert cf.replaced_tokens_for("get_overview", {"architecture": {}}) == cf.OVERVIEW_FLOOR
+ assert cf.replaced_tokens_for("get_health", {"summary": {}}) == cf.HEALTH_FLOOR
+
+
+def test_dead_end_records_debit_row(tmp_path, monkeypatch) -> None:
+ """An error response writes raw=0/distilled=N — a negative net at
+ aggregation, so the ledger stops only ever crediting (E11)."""
+ from repowise.core.distill.store import (
+ OMISSIONS_DB_FILENAME,
+ OMISSIONS_DIRNAME,
+ OmissionStore,
+ )
+ from repowise.server.mcp_server._savings.recorder import record_mcp_dead_end
+
+ db_dir = tmp_path / ".repowise" / OMISSIONS_DIRNAME
+ db_dir.mkdir(parents=True)
+ db_path = db_dir / OMISSIONS_DB_FILENAME
+ OmissionStore(db_path).close() # create the sidecar
+
+ assert record_mcp_dead_end(tmp_path, "get_symbol", 350) is True
+
+ store = OmissionStore(db_path)
+ try:
+ summary = store.savings_summary()
+ per = summary["per_filter"]["get_symbol"]
+ assert per["raw_tokens"] == 0
+ assert per["distilled_tokens"] == 350
+ assert per["saved_tokens"] == -350
+ finally:
+ store.close()
diff --git a/tests/unit/server/mcp/test_search.py b/tests/unit/server/mcp/test_search.py
index c4d665d79..c54dddda6 100644
--- a/tests/unit/server/mcp/test_search.py
+++ b/tests/unit/server/mcp/test_search.py
@@ -76,8 +76,11 @@ class TestDecisionDownweight:
return [
_mk_result("decision:d1", "Use repo-local SQLite", "decision_record", "", 0.57),
_mk_result(
- "file_page:src/auth/service.py", "Auth Service", "file_page",
- "src/auth/service.py", 0.42,
+ "file_page:src/auth/service.py",
+ "Auth Service",
+ "file_page",
+ "src/auth/service.py",
+ 0.42,
),
]
@@ -97,8 +100,11 @@ class TestDecisionDownweight:
return [
_mk_result("decision:d1", "Use repo-local SQLite", "decision_record", "", 0.57),
_mk_result(
- "file_page:src/auth/service.py", "Auth Service", "file_page",
- "src/auth/service.py", 0.42,
+ "file_page:src/auth/service.py",
+ "Auth Service",
+ "file_page",
+ "src/auth/service.py",
+ 0.42,
),
]
@@ -120,8 +126,11 @@ class TestDecisionDownweight:
]
flood.append(
_mk_result(
- "file_page:src/auth/service.py", "Auth Service", "file_page",
- "src/auth/service.py", 0.35,
+ "file_page:src/auth/service.py",
+ "Auth Service",
+ "file_page",
+ "src/auth/service.py",
+ 0.35,
)
)
@@ -148,8 +157,11 @@ class TestDecisionDownweight:
]
flood.append(
_mk_result(
- "file_page:src/auth/service.py", "Auth Service", "file_page",
- "src/auth/service.py", 0.35,
+ "file_page:src/auth/service.py",
+ "Auth Service",
+ "file_page",
+ "src/auth/service.py",
+ 0.35,
)
)
@@ -199,3 +211,109 @@ class TestClassifyHitKind:
from repowise.server.mcp_server.tool_search import _classify_hit_kind
assert _classify_hit_kind("src/auth", "module_page") == "doc"
+
+
+class TestDecisionDemotionAndRescue:
+ """B4: absolute demotion of decisions on non-why queries + window rescue."""
+
+ @pytest.mark.asyncio
+ async def test_decision_outscoring_file_page_still_ranks_below(self, setup_mcp):
+ # The 0.6 down-weight alone is washed out when the decision score
+ # margin exceeds it (0.9 * 0.6 = 0.54 > 0.42). Demotion must be
+ # absolute for non-why queries.
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.server.mcp_server import search_codebase
+
+ async def fake_search(query, limit=10):
+ return [
+ _mk_result("decision:d1", "Cache prompts as SWR", "decision_record", "", 0.9),
+ _mk_result(
+ "file_page:src/auth/service.py",
+ "Auth Service",
+ "file_page",
+ "src/auth/service.py",
+ 0.42,
+ ),
+ ]
+
+ mcp_mod._vector_store.search = fake_search
+ result = await search_codebase("answer cache invalidation schema version")
+ types = [r["page_type"] for r in result["results"]]
+ assert types[0] == "file_page"
+
+ @pytest.mark.asyncio
+ async def test_all_decision_window_is_rescued_with_file_pages(self, setup_mcp):
+ # E6 live failure: 5/5 decision records, zero file pages. The wider
+ # re-fetch must surface non-decision pages.
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.server.mcp_server import search_codebase
+
+ decisions = [
+ _mk_result(f"decision:d{i}", f"Decision {i}", "decision_record", "", 0.8 - i * 0.01)
+ for i in range(20)
+ ]
+ wide = decisions + [
+ _mk_result(
+ "file_page:src/auth/service.py",
+ "Auth Service",
+ "file_page",
+ "src/auth/service.py",
+ 0.3,
+ )
+ ]
+
+ async def fake_search(query, limit=10):
+ # Narrow window: only decisions. Wide window: includes the file.
+ return decisions[:limit] if limit <= 20 else wide[:limit]
+
+ mcp_mod._vector_store.search = fake_search
+ result = await search_codebase("answer cache invalidation schema version", limit=5)
+ types = [r["page_type"] for r in result["results"]]
+ assert "file_page" in types, "rescue must inject non-decision pages"
+ assert types[0] == "file_page", "rescued file page ranks above demoted decisions"
+
+ @pytest.mark.asyncio
+ async def test_why_query_skips_rescue_and_demotion(self, setup_mcp):
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.server.mcp_server import search_codebase
+
+ async def fake_search(query, limit=10):
+ return [
+ _mk_result("decision:d1", "Use SQLite", "decision_record", "", 0.9),
+ _mk_result(
+ "file_page:src/auth/service.py",
+ "Auth Service",
+ "file_page",
+ "src/auth/service.py",
+ 0.42,
+ ),
+ ]
+
+ mcp_mod._vector_store.search = fake_search
+ result = await search_codebase("why did we choose SQLite?")
+ assert result["results"][0]["page_type"] == "decision_record"
+
+
+class TestIdentifierGrepHint:
+ @pytest.mark.asyncio
+ async def test_multiword_query_with_identifier_gets_hint(self, setup_mcp):
+ from repowise.server.mcp_server import search_codebase
+
+ result = await search_codebase("where is _DEFAULT_CO_CHANGE_MIN_COUNT defined")
+ assert "grep_hint" in result
+ assert "_DEFAULT_CO_CHANGE_MIN_COUNT" in result["grep_hint"]
+
+ @pytest.mark.asyncio
+ async def test_camelcase_identifier_gets_hint(self, setup_mcp):
+ from repowise.server.mcp_server import search_codebase
+
+ result = await search_codebase("how does LanguageRegistry resolve specs")
+ assert "grep_hint" in result
+ assert "LanguageRegistry" in result["grep_hint"]
+
+ @pytest.mark.asyncio
+ async def test_plain_english_query_gets_no_hint(self, setup_mcp):
+ from repowise.server.mcp_server import search_codebase
+
+ result = await search_codebase("authentication flow for the service")
+ assert "grep_hint" not in result
diff --git a/tests/unit/server/mcp/test_symbol_range_and_recovery.py b/tests/unit/server/mcp/test_symbol_range_and_recovery.py
new file mode 100644
index 000000000..d7ffb1afd
--- /dev/null
+++ b/tests/unit/server/mcp/test_symbol_range_and_recovery.py
@@ -0,0 +1,112 @@
+"""Range reads and dead-end recovery in get_symbol (C3/C4).
+
+* "path/to/file.py:140-180" serves a live, bounded, always-verified slice
+* an index miss greps the live file and returns fallback_lines instead of
+ a pure-cost dead end
+"""
+
+from __future__ import annotations
+
+import pytest
+
+MODULE_SOURCE = '''"""A module."""
+
+import os
+
+_DEFAULT_MIN_COUNT = 2
+MAX_RETRIES = 5
+
+
+def alpha(x):
+ return x + 1
+
+
+def beta(y):
+ return y * 2
+'''
+
+
+def repo_on_disk(tmp_path, monkeypatch):
+ """Point the MCP repo path at a tmp dir with a real source file."""
+ import repowise.server.mcp_server as mcp_mod
+
+ (tmp_path / "pkg").mkdir()
+ (tmp_path / "pkg" / "mod.py").write_text(MODULE_SOURCE)
+ big = "\n".join(f"line_{i} = {i}" for i in range(1, 401))
+ (tmp_path / "pkg" / "big.py").write_text(big)
+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))
+ return tmp_path
+
+
+async def test_range_read_serves_verified_slice(setup_mcp, repo_on_disk):
+ from repowise.server.mcp_server import get_symbol
+
+ result = await get_symbol("pkg/mod.py:5-6")
+ assert result.get("error") is None
+ assert result["verified"] is True
+ assert result["kind"] == "range"
+ assert result["start_line"] == 5
+ assert result["end_line"] == 6
+ assert "_DEFAULT_MIN_COUNT = 2" in result["source"]
+ assert "MAX_RETRIES = 5" in result["source"]
+
+
+async def test_range_read_caps_at_200_lines(setup_mcp, repo_on_disk):
+ from repowise.server.mcp_server import get_symbol
+
+ result = await get_symbol("pkg/big.py:1-400")
+ assert result["truncated"] is True
+ assert result["end_line"] - result["start_line"] + 1 <= 200
+
+
+async def test_range_read_context_does_not_exceed_cap(setup_mcp, repo_on_disk):
+ from repowise.server.mcp_server import get_symbol
+
+ # 161-line request + 50 lines of context each side would be 261 lines —
+ # the ≤200 contract must hold after context expansion, not just before.
+ result = await get_symbol("pkg/big.py:100-260", context_lines=50)
+ assert result["verified"] is True
+ assert result["end_line"] - result["start_line"] + 1 <= 200
+ assert result["truncated"] is True
+
+
+async def test_range_read_swaps_reversed_bounds(setup_mcp, repo_on_disk):
+ from repowise.server.mcp_server import get_symbol
+
+ result = await get_symbol("pkg/mod.py:6-5")
+ assert result.get("error") is None
+ assert result["start_line"] == 5
+
+
+async def test_double_colon_id_is_not_a_range(setup_mcp, repo_on_disk):
+ from repowise.server.mcp_server import get_symbol
+
+ # "::" forces symbol resolution even though the tail looks numeric-ish.
+ result = await get_symbol("pkg/mod.py::alpha")
+ assert result.get("kind") != "range"
+
+
+async def test_unindexed_constant_recovers_via_live_grep(setup_mcp, repo_on_disk):
+ from repowise.server.mcp_server import get_symbol
+
+ result = await get_symbol("pkg/mod.py::_DEFAULT_MIN_COUNT")
+ assert result.get("resolution") == "live_grep"
+ assert result["verified"] is True
+ [match] = [m for m in result["fallback_lines"] if m["line"] == 5]
+ assert "_DEFAULT_MIN_COUNT = 2" in match["context"]
+ assert "range read" in result["note"]
+
+
+async def test_missing_file_still_errors(setup_mcp, repo_on_disk):
+ from repowise.server.mcp_server import get_symbol
+
+ result = await get_symbol("pkg/ghost.py::nothing")
+ assert "error" in result
diff --git a/tests/unit/server/mcp/test_tombstones.py b/tests/unit/server/mcp/test_tombstones.py
new file mode 100644
index 000000000..863e48f01
--- /dev/null
+++ b/tests/unit/server/mcp/test_tombstones.py
@@ -0,0 +1,132 @@
+"""Tombstone pages for deleted/renamed files (A4).
+
+A ``freshness_status="fresh"`` page for a file that no longer exists is an
+active trap: retrieval serves it, agents cite it. These tests cover the
+marking helper and every serving surface that must skip or redirect.
+"""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import pytest
+from sqlalchemy import select
+
+from repowise.core.persistence.models import Page
+from repowise.core.pipeline.persist import mark_tombstone_pages, tombstone_candidates
+
+
+class TestTombstoneCandidates:
+ def test_deleted_file_has_no_successor(self) -> None:
+ fd = SimpleNamespace(status="deleted", path="src/old.py", old_path=None)
+ assert tombstone_candidates([fd]) == [("src/old.py", [])]
+
+ def test_renamed_file_points_to_new_path(self) -> None:
+ fd = SimpleNamespace(status="renamed", path="src/new.py", old_path="src/old.py")
+ assert tombstone_candidates([fd]) == [("src/old.py", ["src/new.py"])]
+
+ def test_modified_and_added_ignored(self) -> None:
+ fds = [
+ SimpleNamespace(status="modified", path="a.py", old_path=None),
+ SimpleNamespace(status="added", path="b.py", old_path=None),
+ ]
+ assert tombstone_candidates(fds) == []
+
+
+async def test_mark_tombstone_pages_sets_status_and_successors(setup_mcp, session):
+ repo_id = setup_mcp
+ page = (
+ (await session.execute(select(Page).where(Page.target_path == "src/auth/service.py")))
+ .scalars()
+ .first()
+ )
+ assert page is not None, "fixture must seed a page for src/auth/service.py"
+
+ marked = await mark_tombstone_pages(
+ session, repo_id, [("src/auth/service.py", ["src/auth/service_v2.py"])]
+ )
+ await session.commit()
+
+ assert marked == 1
+ await session.refresh(page)
+ assert page.freshness_status == "tombstone"
+ assert json.loads(page.metadata_json)["successor_paths"] == ["src/auth/service_v2.py"]
+
+
+async def test_get_context_returns_tombstone_redirect(setup_mcp, session):
+ repo_id = setup_mcp
+ from repowise.server.mcp_server import get_context
+
+ await mark_tombstone_pages(
+ session, repo_id, [("src/auth/service.py", ["src/auth/service_v2.py"])]
+ )
+ await session.commit()
+
+ result = await get_context(["src/auth/service.py"], include=["docs"])
+ t = result["targets"]["src/auth/service.py"]
+ assert "tombstone" in t["error"]
+ assert t["successor_paths"] == ["src/auth/service_v2.py"]
+ assert "service_v2" in t["hint"]
+
+
+async def test_search_drops_tombstoned_pages(setup_mcp, session, monkeypatch):
+ repo_id = setup_mcp
+ import repowise.server.mcp_server as mcp_mod
+ from repowise.core.persistence.search import SearchResult
+ from repowise.server.mcp_server import search_codebase
+
+ await mark_tombstone_pages(session, repo_id, [("src/auth/service.py", [])])
+ await session.commit()
+
+ async def fake_search(query, limit=10):
+ return [
+ SearchResult(
+ page_id="file_page:src/auth/service.py",
+ title="Auth Service",
+ page_type="file_page",
+ target_path="src/auth/service.py",
+ score=0.9,
+ snippet="auth",
+ search_type="vector",
+ ),
+ SearchResult(
+ page_id="file_page:src/db/models.py",
+ title="DB Models",
+ page_type="file_page",
+ target_path="src/db/models.py",
+ score=0.5,
+ snippet="models",
+ search_type="vector",
+ ),
+ ]
+
+ mcp_mod._vector_store.search = fake_search
+ result = await search_codebase("auth service")
+ ids = [r["page_id"] for r in result["results"]]
+ assert "file_page:src/auth/service.py" not in ids
+ assert "file_page:src/db/models.py" in ids
+
+
+async def test_answer_hydration_drops_tombstoned_pages(setup_mcp, session):
+ repo_id = setup_mcp
+ from repowise.server.mcp_server._answer_pipeline import hydrate_hits
+
+ await mark_tombstone_pages(session, repo_id, [("src/auth/service.py", [])])
+ await session.commit()
+
+ import repowise.server.mcp_server as mcp_mod
+
+ ctx = SimpleNamespace(session_factory=mcp_mod._session_factory)
+ hits = [
+ {"page_id": "file_page:src/auth/service.py", "score": 5.0},
+ {"page_id": "file_page:src/db/models.py", "score": 4.0},
+ ]
+ out = await hydrate_hits(hits, ctx)
+ paths = [h["target_path"] for h in out]
+ assert "src/auth/service.py" not in paths
+ assert "src/db/models.py" in paths
diff --git a/tests/unit/server/mcp/test_verify_bounds.py b/tests/unit/server/mcp/test_verify_bounds.py
new file mode 100644
index 000000000..d62229e6a
--- /dev/null
+++ b/tests/unit/server/mcp/test_verify_bounds.py
@@ -0,0 +1,208 @@
+"""Serve-time bounds verification for get_symbol (the trust contract).
+
+WikiSymbol line bounds are written at index time; the file may have changed
+since. These tests cover the two-tier check: cheap name-on-line gate, then
+one-file re-parse with bound correction, then the approximate fallback.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.persistence.models import WikiSymbol, _new_uuid
+from repowise.server.mcp_server._verify import (
+ check_symbol_bounds,
+ end_anchor_holds,
+ heal_symbol_row,
+ name_at_line,
+ relocate_symbol,
+)
+
+FRESH_SOURCE = '''"""Module."""
+
+
+def alpha(x):
+ return x + 1
+
+
+class Service:
+ def handle(self, req):
+ return req
+'''
+
+# alpha's body grew by two lines but its definition line is unchanged — the
+# stored end (5) now truncates the body (real end is 7). The start gate alone
+# would pass and serve a short slice marked verified.
+GROWN_SOURCE = '''"""Module."""
+
+
+def alpha(x):
+ y = x + 1
+ z = y + 1
+ return z
+
+
+class Service:
+ def handle(self, req):
+ return req
+'''
+
+# Same file with 4 lines inserted above alpha — every stored bound is stale.
+SHIFTED_SOURCE = '''"""Module."""
+
+import os
+import sys
+
+
+NEW_CONSTANT = 7
+
+
+def alpha(x):
+ return x + 1
+
+
+class Service:
+ def handle(self, req):
+ return req
+'''
+
+
+def _row(**overrides) -> WikiSymbol:
+ defaults = dict(
+ id=_new_uuid(),
+ repository_id="repo-1",
+ file_path="pkg/mod.py",
+ symbol_id="pkg/mod.py::alpha",
+ name="alpha",
+ qualified_name="pkg.mod.alpha",
+ kind="function",
+ signature="def alpha(x)",
+ start_line=4,
+ end_line=5,
+ language="python",
+ )
+ defaults.update(overrides)
+ return WikiSymbol(**defaults)
+
+
+class TestNameAtLine:
+ def test_name_on_stored_line_passes(self) -> None:
+ assert name_at_line(FRESH_SOURCE.splitlines(), "alpha", 4)
+
+ def test_moved_definition_fails(self) -> None:
+ assert not name_at_line(SHIFTED_SOURCE.splitlines(), "alpha", 4)
+
+ def test_out_of_range_line_fails(self) -> None:
+ assert not name_at_line(FRESH_SOURCE.splitlines(), "alpha", 999)
+
+ def test_qualified_name_uses_bare_segment(self) -> None:
+ assert name_at_line(FRESH_SOURCE.splitlines(), "Service::handle", 9)
+
+
+class TestCheckSymbolBounds:
+ def test_fresh_bounds_verified_without_reparse(self) -> None:
+ check = check_symbol_bounds(_row(), FRESH_SOURCE)
+ assert check.verified
+ assert not check.corrected
+ assert (check.start_line, check.end_line) == (4, 5)
+
+ def test_stale_bounds_corrected_via_reparse(self) -> None:
+ check = check_symbol_bounds(_row(), SHIFTED_SOURCE)
+ assert check.verified
+ assert check.corrected
+ # alpha moved from line 4 to line 10 in the shifted source.
+ assert check.start_line == 10
+ slice_lines = SHIFTED_SOURCE.splitlines()[check.start_line - 1 : check.end_line]
+ assert "def alpha(x):" in slice_lines[0]
+
+ def test_deleted_symbol_is_approximate(self) -> None:
+ row = _row(name="ghost", symbol_id="pkg/mod.py::ghost", qualified_name="ghost")
+ check = check_symbol_bounds(row, SHIFTED_SOURCE)
+ assert not check.verified
+ assert check.approximate
+
+ def test_method_relocated_by_name_and_parent(self) -> None:
+ row = _row(
+ name="handle",
+ symbol_id="pkg/mod.py::Service::handle",
+ qualified_name="Service::handle",
+ kind="method",
+ parent_name="Service",
+ start_line=9,
+ end_line=10,
+ )
+ check = check_symbol_bounds(row, SHIFTED_SOURCE)
+ assert check.verified
+ assert check.corrected
+ assert "def handle" in SHIFTED_SOURCE.splitlines()[check.start_line - 1]
+
+ def test_interior_body_growth_forces_correction(self) -> None:
+ # Definition line unchanged, but the body grew — the start gate passes
+ # yet the stored end (5) truncates the symbol. The end anchor must
+ # catch it and re-parse to the true end (7), not serve a short slice.
+ check = check_symbol_bounds(_row(), GROWN_SOURCE)
+ assert check.verified
+ assert check.corrected
+ assert (check.start_line, check.end_line) == (4, 7)
+
+ def test_short_name_skips_cheap_gate(self) -> None:
+ # "db" is a substring of "dbquery()" but isn't this symbol. A 1-2 char
+ # name must not be rubber-stamped by substring containment; with no
+ # real symbol to relocate, the result is approximate, not verified.
+ src = "result = self.dbquery()\n"
+ row = _row(
+ name="db", symbol_id="pkg/mod.py::db", qualified_name="db", start_line=1, end_line=1
+ )
+ check = check_symbol_bounds(row, src)
+ assert not check.verified
+ assert check.approximate
+
+
+class TestEndAnchor:
+ def test_eof_after_symbol_holds(self) -> None:
+ assert end_anchor_holds(FRESH_SOURCE.splitlines(), 8, 10)
+
+ def test_blank_line_after_symbol_holds(self) -> None:
+ assert end_anchor_holds(FRESH_SOURCE.splitlines(), 4, 5)
+
+ def test_deeper_indent_after_stored_end_fails(self) -> None:
+ # Line 6 (" z = y + 1") is still body — stored end of 5 is wrong.
+ assert not end_anchor_holds(GROWN_SOURCE.splitlines(), 4, 5)
+
+ def test_out_of_range_end_fails(self) -> None:
+ assert not end_anchor_holds(FRESH_SOURCE.splitlines(), 4, 0)
+
+
+class TestRelocateSymbol:
+ def test_relocate_finds_exact_symbol_id(self) -> None:
+ located = relocate_symbol(_row(), SHIFTED_SOURCE)
+ assert located is not None
+ assert located[0] == 10
+
+ def test_relocate_returns_none_for_missing_symbol(self) -> None:
+ row = _row(name="ghost", symbol_id="pkg/mod.py::ghost")
+ assert relocate_symbol(row, SHIFTED_SOURCE) is None
+
+ def test_relocate_handles_unparseable_language(self) -> None:
+ row = _row(language="no-such-language")
+ assert relocate_symbol(row, SHIFTED_SOURCE) is None
+
+
+async def test_heal_symbol_row_persists_corrected_bounds(setup_mcp, factory, session):
+ from sqlalchemy import select
+
+ from repowise.core.persistence.models import Repository
+
+ repo = (await session.execute(select(Repository))).scalars().first()
+ row = _row(repository_id=repo.id)
+ session.add(row)
+ await session.commit()
+
+ await heal_symbol_row(factory, row, 42, 57)
+
+ from repowise.core.persistence.database import get_session
+
+ async with get_session(factory) as s:
+ healed = (await s.execute(select(WikiSymbol).where(WikiSymbol.id == row.id))).scalar_one()
+ assert (healed.start_line, healed.end_line) == (42, 57)