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(answer): surface a recorded fact that disagrees with an answer (#1318)

Raghav Chamadiya00ed16ff24b2
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 92a37b2cc..79389b501 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
@@ -15,6 +15,12 @@ search → context → read loop with one tool call that returns:
follow-up); present only when the answer
names a function/method/class that was
hydrated
+ "episodes": list — at most one dated fact recorded about this
+ checkout that bears on the question, served
+ beside the answer and never in place of it;
+ present only when its scope intersects the
+ answer's and confidence is below high (see
+ ``episodes``)
"more_definitions": list only on an answer-by-union (homonym) reply
whose bodies overflowed the char budget:
{file, name, line, symbol_id, hint} entries
@@ -134,6 +140,9 @@ from repowise.server.mcp_server.tool_answer.data_shape import (
_is_data_shape_question,
mine_data_shape,
)
+from repowise.server.mcp_server.tool_answer.episodes import (
+ attach_episode as _attach_episode,
+)
from repowise.server.mcp_server.tool_answer.retrieval import (
_apply_domain_penalty,
_attach_page_excerpts,
@@ -680,6 +689,9 @@ async def get_answer(
retrieval_quality separately rates the retrieval that fed synthesis.
When the answer names a function/method/class, ``symbol_bodies`` carries
its full live body — read that instead of a follow-up get_symbol.
+ ``episodes``, when present, is a dated fact recorded about this checkout
+ that bears on the question — evidence beside the answer, not a correction
+ of it. Weigh it against the answer; ``still_true`` says how current it is.
Args:
question: developer question.
@@ -820,6 +832,16 @@ async def get_answer(
targets=[p for p in cached_paths if isinstance(p, str) and p],
)
_apply_lean_high(payload, question)
+ # Serve-time, on this path as well as the fresh one: the
+ # episode is read on every call and never cached into an
+ # answer, so a disagreement cannot be frozen into a row and
+ # served after the episode has been superseded.
+ await _attach_episode(
+ payload,
+ question=question,
+ repo_path=getattr(ctx, "path", None),
+ repo_name=getattr(repository, "name", None),
+ )
return payload
# --- Retrieval pipeline ------------------------------------------------
@@ -1802,4 +1824,16 @@ async def get_answer(
if degraded := _degraded_legs(_retrieval_legs()):
payload["_meta"]["retrieval_degraded"] = degraded
_apply_lean_high(payload, question)
+ # After the cache write above, deliberately. ``cache_payload`` is a shallow
+ # copy taken before this point, so the episode reaches the caller and never
+ # the cache row — which is why adding it needs no _ANSWER_SCHEMA_VERSION
+ # bump: a row written before this change and one written after are the same
+ # bytes, and bumping would invalidate every user's cache for a field that
+ # is not in it.
+ await _attach_episode(
+ payload,
+ question=question,
+ repo_path=getattr(ctx, "path", None),
+ repo_name=getattr(repository, "name", None),
+ )
return payload
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py b/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py
new file mode 100644
index 000000000..b6e78ebbf
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py
@@ -0,0 +1,388 @@
+"""Attach a dated episode that disagrees with a synthesised answer.
+
+``get_answer`` reasons from the code as it is now, and it is confidently wrong
+about what was *decided*. The reproduction this module exists for: asked
+whether to run the declared formatter before committing, the tool reads a
+``format`` target out of the build files and answers yes — while the checkout's
+own episode store holds a ``formatter_drift`` record saying the tree is not
+formatter-clean and a repo-wide run would produce a large unrelated diff.
+
+**Add, never replace.** The synthesis stays exactly as it was; a matching
+episode is appended beside it as a dated, attributed quotation. Replacing the
+answer would introduce the failure this exists to prevent, because the episode
+is sometimes the stale one and the synthesis the correct one. A reader who sees
+"recorded at ``acd24602``" next to "run the formatter" does not run it, and
+nothing is lost when the episode has expired.
+
+Three preconditions, checked in this order:
+
+1. the episode's scope intersects the answer's,
+2. the episode is still true,
+3. the synthesis is below ``confidence: high``.
+
+Any one missing means silence, and silence is byte-identical to today's
+payload. This runs at **serve time on both the fresh and the cached path**, so
+the episode is read fresh on every call and a disagreement is never frozen into
+a cache row — which is also why adding it needs no answer-schema bump.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import subprocess
+import time
+from pathlib import Path
+
+from repowise.core.precedent.store import EpisodeStore, default_store_path
+from repowise.server.mcp_server._budget import OmissionCollector, effective_char_budget
+
+_log = logging.getLogger(__name__)
+
+#: Only ever one episode. A cap on a *count* is not a bound on a response whose
+#: fields are free text, so the body is capped separately below.
+_MAX_EPISODES = 1
+
+#: Ceiling on the quoted body. Overflow is handed to the omission store so it
+#: stays recoverable via ``repowise expand`` rather than vanishing.
+_MAX_BODY_CHARS = 600
+
+#: How many scoped candidates are tested for staleness before giving up. Each
+#: test may cost one git query, so this is what keeps the sanctioned read-time
+#: exception bounded no matter how large the store grows.
+_MAX_SCOPED_CANDIDATES = 4
+
+#: Room the block needs before it is worth attaching at all.
+_BLOCK_OVERHEAD_CHARS = 400
+
+#: Seconds allowed for the one sanctioned read-time git query. Measured at
+#: 55-66 ms on a 1,000-commit repository; the timeout is for the pathological
+#: case (a cold, very large repo), where saying nothing is the right answer.
+_GIT_TIMEOUT_S = 2.0
+
+_LEAD_IN = (
+ "A dated record from this checkout is attached in `episodes` — evidence "
+ "recorded at a point in time, not a correction of the answer above."
+)
+
+
+async def attach_episode(
+ payload: dict,
+ *,
+ question: str,
+ repo_path: str | Path | None,
+ repo_name: str | None,
+) -> None:
+ """Append a scoped, still-true episode to *payload*. Never raises.
+
+ Async only to keep the SQLite read and the git query off the event loop;
+ all the work happens in :func:`attach_episode_sync`.
+ """
+ try:
+ await asyncio.to_thread(
+ attach_episode_sync,
+ payload,
+ question=question,
+ repo_path=repo_path,
+ repo_name=repo_name,
+ )
+ except Exception: # pragma: no cover - defensive; a disagreement is a bonus
+ _log.warning("get_answer episode attach failed", exc_info=True)
+
+
+def attach_episode_sync(
+ payload: dict,
+ *,
+ question: str,
+ repo_path: str | Path | None,
+ repo_name: str | None,
+) -> None:
+ """Synchronous body of :func:`attach_episode`. Never raises."""
+ try:
+ _attach(
+ payload,
+ question=question,
+ repo_path=repo_path,
+ repo_name=repo_name,
+ )
+ except Exception:
+ _log.warning("get_answer episode attach failed", exc_info=True)
+
+
+def _attach(
+ payload: dict,
+ *,
+ question: str,
+ repo_path: str | Path | None,
+ repo_name: str | None,
+) -> None:
+ # Precondition 3 first: it is free, and a high-confidence answer is the one
+ # case where appending a disagreement is more likely to mislead than help.
+ if payload.get("confidence") == "high":
+ return
+ answer_text = (payload.get("answer") or "").strip()
+ if not answer_text or not repo_path:
+ return
+
+ root = Path(repo_path)
+ store_path = default_store_path(root)
+ # Opening the store would CREATE it. A repo that never derived episodes
+ # must not grow a database because someone called get_answer.
+ if not store_path.is_file():
+ return
+
+ try:
+ with EpisodeStore(store_path) as store:
+ rows = store.list_episodes()
+ except Exception:
+ _log.warning("episode store read failed", exc_info=True)
+ return
+ if not rows:
+ return
+
+ haystack = f"{question}\n{answer_text}".casefold()
+ answer_paths = _answer_paths(payload)
+
+ scoped = []
+ for row in rows:
+ matched = _scope(row, haystack=haystack, answer_paths=answer_paths, repo_name=repo_name)
+ if matched is not None:
+ scoped.append((row, matched))
+ if not scoped:
+ return
+
+ # Most specific first: a path match is stronger evidence of relevance than
+ # a subject phrase, and among equals the longer subject is the rarer term.
+ scoped.sort(
+ key=lambda pair: (len(pair[1]), len(pair[0]["subject"]), pair[0]["id"]),
+ reverse=True,
+ )
+
+ # Staleness is evaluated in rank order and only until one episode passes,
+ # so the git query runs at most once on the common path. A stale top match
+ # falls through to the next rather than silencing a still-true one below
+ # it, but only _MAX_EPISODES are ever emitted.
+ emitted = 0
+ for row, matched in scoped[:_MAX_SCOPED_CANDIDATES]:
+ if emitted >= _MAX_EPISODES:
+ break
+ verdict = _still_true(row, root=root)
+ if verdict is None:
+ continue # precondition 2 failed outright — say nothing
+ if _emit(payload, row, matched=matched, verdict=verdict, repo_root=root):
+ emitted += 1
+
+
+# -- precondition 1: scope ---------------------------------------------------
+
+
+def _scope(
+ row: dict,
+ *,
+ haystack: str,
+ answer_paths: set[str],
+ repo_name: str | None,
+) -> list[str] | None:
+ """The part of the answer this episode is about, or None if it is not.
+
+ Two rules, one per shape of episode. An episode that names files is scoped
+ by those files. An episode with an **empty node set is a claim about the
+ checkout as a whole** — it is not "unknown scope", and it does not
+ therefore intersect everything: read that way, the repo-wide facts would
+ ride along on every sub-high-confidence answer in the repository, which is
+ the noise this gate exists to prevent. Repo-wide episodes are scoped by
+ their subject instead, which the store already defines as the field that
+ discriminates episodes within a kind.
+ """
+ nodes = [n for n in (row.get("nodes") or []) if isinstance(n, str) and n]
+ if nodes:
+ return sorted({p for p in answer_paths if _covers(nodes, p)}) or None
+
+ subject = (row.get("subject") or "").strip()
+ # A subject with no word character (``nested_repos`` uses ``.`` for the
+ # repo root) is not a topic — and ``\b`` around pure punctuation matches in
+ # places no reader would call a mention.
+ if not re.search(r"\w", subject):
+ return None
+ # A subject equal to the repository's own name has no topic scope: every
+ # answer in a repo names the repo, so matching on it is matching on
+ # nothing.
+ if repo_name and subject.casefold() == repo_name.strip().casefold():
+ return None
+ if not re.search(rf"\b{re.escape(subject.casefold())}\b", haystack):
+ return None
+ return []
+
+
+def _covers(nodes: list[str], path: str) -> bool:
+ """True when *path* is one of *nodes* or sits underneath one."""
+ norm = path.replace("\\", "/").strip("/")
+ for node in nodes:
+ n = node.replace("\\", "/").strip("/")
+ if norm == n or norm.startswith(f"{n}/"):
+ return True
+ return False
+
+
+def _answer_paths(payload: dict) -> set[str]:
+ """Every repo path the answer resolved, from all four places they land."""
+ paths: set[str] = set()
+ for key in ("citations", "fallback_targets"):
+ paths.update(p for p in (payload.get(key) or []) if isinstance(p, str))
+ for hit in payload.get("retrieval") or []:
+ if isinstance(hit, dict):
+ paths.update(
+ p for p in (hit.get("path"), hit.get("target_path")) if isinstance(p, str)
+ )
+ for guess in payload.get("best_guesses") or []:
+ if isinstance(guess, dict) and isinstance(guess.get("file"), str):
+ paths.add(guess["file"])
+ return {p for p in paths if p}
+
+
+# -- precondition 2: still true ----------------------------------------------
+
+
+def _still_true(row: dict, *, root: Path) -> str | None:
+ """How this episode's truth was established, or None to stay silent.
+
+ Measured against the checkout's live ``HEAD``, not the indexed commit: an
+ episode is a claim about the tree on disk, and that is the tree the reader
+ is about to act on.
+
+ Three cases, and the third is the one worth reading.
+
+ *Re-observed.* Every index refreshes ``last_seen_at`` for a fact that still
+ holds, so a stamp later than ``birth_at`` is proof of currency that costs
+ no git call at all.
+
+ *Node-scoped.* ``git rev-list --count <birth>..HEAD -- <nodes>`` is the
+ real question, and zero is a real answer. Anything else — including a git
+ failure — means we cannot vouch for it, so it is suppressed. Precision at
+ the acting stage is close to absolute.
+
+ *Repo-wide, derived once.* Git cannot decide this one. Its scope is the
+ whole tree, so any commit at all makes the count non-zero, and the fact it
+ asserts ("the tree is not formatter-clean") is not what a commit falsifies
+ — running the formatter is. Suppressing here would retire the record on the
+ very next commit and leave a guard that only passes its own tests. So the
+ age **labels** rather than suppresses: it is served with its birth commit
+ and how far the tree has moved since, and the reader discounts it. Under
+ add-never-replace a stale episode overrides nothing, and the asymmetry runs
+ the right way — believing it costs one skipped formatter run, disbelieving
+ it costs a reformatted tree in a pull request.
+ """
+ birth_at = row.get("birth_at") or 0.0
+ last_seen = row.get("last_seen_at") or 0.0
+ recorded = _recorded_on(birth_at)
+ if last_seen > birth_at:
+ return f"re-observed by a later index (recorded {recorded})"
+
+ birth_commit = row.get("birth_commit")
+ nodes = [n for n in (row.get("nodes") or []) if isinstance(n, str) and n]
+
+ if nodes:
+ if not birth_commit:
+ return f"recorded {recorded}; not re-checked since"
+ changed = _commits_since(root, birth_commit, nodes)
+ if changed is None or changed > 0:
+ return None
+ return f"nothing in its scope has changed since {_short(birth_commit)} (recorded {recorded})"
+
+ if not birth_commit:
+ return f"recorded {recorded}; a standing claim about this checkout"
+ moved = _commits_since(root, birth_commit, [])
+ if moved is None:
+ return f"recorded {recorded} at {_short(birth_commit)}; not re-checked since"
+ if moved == 0:
+ return f"recorded {recorded} at {_short(birth_commit)}, the current commit"
+ plural = "commit" if moved == 1 else "commits"
+ return (
+ f"recorded {recorded} at {_short(birth_commit)}; the tree has moved "
+ f"{moved} {plural} since and this was not re-checked"
+ )
+
+
+def _commits_since(root: Path, birth_commit: str, nodes: list[str]) -> int | None:
+ """``git rev-list --count <birth>..HEAD [-- nodes]``. None on any failure.
+
+ The one sanctioned read-time computation in this path, and it is bounded:
+ a single plumbing call with a hard timeout, measured at 55-66 ms against
+ get_answer's multi-second synthesis. A budget that quietly produces a
+ partial count is worse than no answer, so every failure mode returns None
+ and the caller decides what silence means.
+ """
+ cmd = ["git", "rev-list", "--count", f"{birth_commit}..HEAD"]
+ if nodes:
+ cmd += ["--", *nodes]
+ try:
+ completed = subprocess.run(
+ cmd,
+ cwd=str(root),
+ capture_output=True,
+ text=True,
+ timeout=_GIT_TIMEOUT_S,
+ )
+ except (subprocess.TimeoutExpired, OSError):
+ return None
+ if completed.returncode != 0:
+ return None
+ try:
+ return int(completed.stdout.strip())
+ except ValueError:
+ return None
+
+
+def _recorded_on(birth_at: float) -> str:
+ if not birth_at:
+ return "at an unknown date"
+ return time.strftime("%Y-%m-%d", time.gmtime(birth_at))
+
+
+def _short(sha: str) -> str:
+ return sha[:12]
+
+
+# -- emission ----------------------------------------------------------------
+
+
+def _emit(
+ payload: dict,
+ row: dict,
+ *,
+ matched: list[str],
+ verdict: str,
+ repo_root: Path,
+) -> bool:
+ """Append the episode block, budgeted, without touching the answer.
+
+ False when there was no room for it, so the caller does not count a block
+ it did not emit.
+ """
+ if len(json.dumps(payload, default=str)) + _BLOCK_OVERHEAD_CHARS > effective_char_budget():
+ return False
+
+ body = row.get("body") or ""
+ collector: OmissionCollector | None = None
+ if len(body) > _MAX_BODY_CHARS:
+ collector = OmissionCollector("get_answer", repo_root)
+ marker = collector.add_inline(f"episode:{row.get('kind')}", body)
+ body = body[:_MAX_BODY_CHARS].rstrip() + (f" {marker}" if marker else " …")
+
+ entry = {
+ "tier": row.get("tier"),
+ "kind": row.get("kind"),
+ "subject": row.get("subject"),
+ "recorded": body,
+ "evidence": row.get("evidence"),
+ "scope": matched or "the checkout as a whole",
+ "still_true": verdict,
+ }
+ payload.setdefault("episodes", []).append(entry)
+ if _LEAD_IN not in (payload.get("note") or ""):
+ payload["note"] = f"{payload['note']} {_LEAD_IN}" if payload.get("note") else _LEAD_IN
+ if collector is not None:
+ collector.attach(payload)
+ return True
diff --git a/tests/unit/server/mcp/test_answer_episodes.py b/tests/unit/server/mcp/test_answer_episodes.py
new file mode 100644
index 000000000..43010bc1c
--- /dev/null
+++ b/tests/unit/server/mcp/test_answer_episodes.py
@@ -0,0 +1,455 @@
+"""The get_answer contradiction guard.
+
+The reproduction these tests exist for: asked whether to run the declared
+formatter before committing, ``get_answer`` reads a ``format`` target out of
+the build files and answers yes, at ``confidence: medium``, while the
+checkout's own episode store holds a ``formatter_drift`` record saying the
+tree is not formatter-clean. The guard appends the record beside the answer.
+
+The anti-reproductions matter more than the reproduction: a guard that fires
+when it should not is the failure this feature exists to prevent, so most of
+what follows asserts a **byte-identical** payload.
+"""
+
+from __future__ import annotations
+
+import copy
+import subprocess
+import time
+
+import pytest
+
+from repowise.core.precedent.store import (
+ TIER_STRUCTURAL,
+ Episode,
+ EpisodeStore,
+ default_store_path,
+)
+from repowise.server.mcp_server.tool_answer.episodes import attach_episode_sync
+
+FORMATTER_ANSWER = (
+ "**Yes — run `ruff format` before committing.** This repo defines a "
+ "`format` target, which usually means CI will fail if files are not "
+ "already formatted."
+)
+
+
+# -- fixtures ----------------------------------------------------------------
+
+
+def repo(tmp_path):
+ """A git checkout with a .repowise directory, one commit deep."""
+ root = tmp_path / "checkout"
+ (root / ".repowise").mkdir(parents=True)
+ (root / "pyproject.toml").write_text("[project]\nname = 'demo'\n", encoding="utf-8")
+ _git(root, "init", "-q")
+ _git(root, "config", "user.email", "[email protected]")
+ _git(root, "config", "user.name", "T")
+ _git(root, "add", "-A")
+ _git(root, "commit", "-qm", "first")
+ return root
+
+
+def _git(root, *args):
+ subprocess.run(["git", *args], cwd=str(root), check=True, capture_output=True)
+
+
+def _head(root) -> str:
+ out = subprocess.run(
+ ["git", "rev-parse", "HEAD"], cwd=str(root), capture_output=True, text=True, check=True
+ )
+ return out.stdout.strip()
+
+
+def _write(root, episode: Episode, *, born: float, seen: float | None = None):
+ """Persist *episode* with an explicit birth/last-seen pair.
+
+ ``replace_kinds`` stamps both from one clock, which is exactly the
+ "derived once, never re-observed" state; a later re-observation is
+ simulated by moving ``last_seen_at`` forward on its own.
+ """
+ with EpisodeStore(default_store_path(root)) as store:
+ store.replace_kinds(
+ tier=episode.tier, kinds=[episode.kind], episodes=[episode], now=born
+ )
+ if seen is not None:
+ # Reaches past the write API on purpose: `replace_kinds` stamps
+ # birth and last-seen from one clock, so a later re-observation
+ # has no public expression.
+ store._conn.execute(
+ "UPDATE episodes SET last_seen_at = ? WHERE id = ?", (seen, episode.id)
+ )
+ store._conn.commit()
+
+
+def formatter_episode(birth_commit: str | None) -> Episode:
+ return Episode(
+ tier=TIER_STRUCTURAL,
+ kind="formatter_drift",
+ subject="ruff format",
+ body="This tree is not formatter-clean: 419 files would be reformatted.",
+ evidence="ruff format --check .: 419 files would be reformatted",
+ nodes=(),
+ birth_commit=birth_commit,
+ )
+
+
+def payload(**over) -> dict:
+ base = {
+ "answer": FORMATTER_ANSWER,
+ "citations": ["Makefile"],
+ "confidence": "medium",
+ "retrieval_quality": "weak",
+ "fallback_targets": ["pyproject.toml"],
+ "retrieval": [],
+ }
+ base.update(over)
+ return base
+
+
+def run(p, repo, *, question="should I run ruff format before committing", name="demo"):
+ attach_episode_sync(p, question=question, repo_path=repo, repo_name=name)
+ return p
+
+
+# -- the reproduction --------------------------------------------------------
+
+
+def test_formatter_episode_appears_beside_the_answer(repo):
+ _write(repo, formatter_episode(_head(repo)), born=time.time())
+
+ got = run(payload(), repo)
+
+ assert len(got["episodes"]) == 1
+ episode = got["episodes"][0]
+ assert episode["kind"] == "formatter_drift"
+ assert "419 files" in episode["recorded"]
+ assert episode["scope"] == "the checkout as a whole"
+ # Add, never replace: the synthesis is untouched.
+ assert got["answer"] == FORMATTER_ANSWER
+ assert got["confidence"] == "medium"
+ # It arrives as dated evidence, not as an instruction.
+ assert "not a correction" in got["note"]
+
+
+def test_repo_wide_episode_survives_the_tree_moving_on(repo):
+ """A commit does not falsify "the tree is not formatter-clean".
+
+ Its scope is the whole tree, so any commit makes ``git rev-list --count``
+ non-zero. Suppressing on that retires the record on the very next commit
+ and leaves a guard that only passes its own tests, so the age labels
+ rather than suppresses.
+ """
+ born_at = _head(repo)
+ _write(repo, formatter_episode(born_at), born=time.time())
+ (repo / "later.txt").write_text("x", encoding="utf-8")
+ _git(repo, "add", "-A")
+ _git(repo, "commit", "-qm", "second")
+
+ got = run(payload(), repo)
+
+ assert got["episodes"][0]["still_true"] == (
+ f"recorded {time.strftime('%Y-%m-%d', time.gmtime())} at {born_at[:12]}; "
+ "the tree has moved 1 commit since and this was not re-checked"
+ )
+
+
+# -- the anti-reproductions --------------------------------------------------
+
+
+def test_high_confidence_is_byte_identical(repo):
+ _write(repo, formatter_episode(_head(repo)), born=time.time())
+ before = payload(confidence="high")
+
+ assert run(copy.deepcopy(before), repo) == before
+
+
+def test_an_empty_store_changes_nothing(repo):
+ before = payload()
+
+ assert run(copy.deepcopy(before), repo) == before
+
+
+def test_no_store_at_all_changes_nothing_and_creates_nothing(tmp_path):
+ """A repo that never derived episodes must not grow a database."""
+ root = tmp_path / "bare"
+ root.mkdir()
+ before = payload()
+ after = copy.deepcopy(before)
+
+ attach_episode_sync(after, question="ruff format?", repo_path=root, repo_name="bare")
+
+ assert after == before
+ assert not default_store_path(root).exists()
+
+
+def test_an_unrelated_question_changes_nothing(repo):
+ """Scope is the whole filter; an empty node set is not a wildcard."""
+ _write(repo, formatter_episode(_head(repo)), born=time.time())
+ before = payload(
+ answer="`_serialize_hits` trims each hit to a summary.",
+ citations=["answer.py"],
+ fallback_targets=[],
+ )
+
+ got = run(copy.deepcopy(before), repo, question="how does _serialize_hits work")
+
+ assert got == before
+
+
+def test_a_node_scoped_episode_is_suppressed_once_its_scope_changes(repo):
+ """Where git *can* decide, precondition 2 stays absolute."""
+ (repo / "backend").mkdir()
+ (repo / "backend" / "main.py").write_text("x = 1\n", encoding="utf-8")
+ _git(repo, "add", "-A")
+ _git(repo, "commit", "-qm", "add backend")
+ born_at = _head(repo)
+ _write(
+ repo,
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind="nested_repos",
+ subject=".",
+ body="backend is a separate git repository.",
+ evidence="walk stopped at a nested .git boundary",
+ nodes=("backend",),
+ birth_commit=born_at,
+ ),
+ born=time.time(),
+ )
+ asked = payload(answer="Routers are registered in backend/main.py.", citations=["backend/main.py"])
+
+ # Nothing in scope has changed yet, so it is served.
+ served = run(copy.deepcopy(asked), repo, question="where are routers registered")
+ assert served["episodes"][0]["scope"] == ["backend/main.py"]
+
+ # Touch the scope, and it goes quiet rather than vouching for itself.
+ (repo / "backend" / "main.py").write_text("x = 2\n", encoding="utf-8")
+ _git(repo, "add", "-A")
+ _git(repo, "commit", "-qm", "touch backend")
+
+ assert run(copy.deepcopy(asked), repo, question="where are routers registered") == asked
+
+
+def test_a_re_observed_episode_needs_no_git_query(repo):
+ """``last_seen_at > birth_at`` is proof of currency that costs nothing."""
+ now = time.time()
+ _write(repo, formatter_episode(_head(repo)), born=now, seen=now + 60)
+
+ got = run(payload(), repo)
+
+ assert got["episodes"][0]["still_true"] == (
+ f"re-observed by a later index (recorded {time.strftime('%Y-%m-%d', time.gmtime(now))})"
+ )
+
+
+def test_without_git_a_repo_wide_fact_is_served_and_a_scoped_one_is_not(tmp_path):
+ """An index with no git checkout (a tarball, a hosted job) still degrades.
+
+ ``git rev-list`` cannot answer either question here. The repo-wide fact
+ says so and is served; the node-scoped one cannot be vouched for and goes
+ quiet, which is the asymmetry precondition 2 encodes.
+ """
+ root = tmp_path / "nogit"
+ (root / ".repowise").mkdir(parents=True)
+ born = time.time()
+ _write(root, formatter_episode("deadbeef" * 5), born=born)
+ _write(
+ root,
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind="nested_repos",
+ subject="vendor",
+ body="vendor is a separate git repository.",
+ evidence="walk stopped at a nested .git boundary",
+ nodes=("vendor",),
+ birth_commit="deadbeef" * 5,
+ ),
+ born=born,
+ )
+
+ wide = payload()
+ attach_episode_sync(
+ wide, question="should I run ruff format?", repo_path=root, repo_name="nogit"
+ )
+ assert wide["episodes"][0]["kind"] == "formatter_drift"
+ assert "not re-checked since" in wide["episodes"][0]["still_true"]
+
+ scoped = payload(answer="It lives in vendor/lib.py.", citations=["vendor/lib.py"])
+ before = copy.deepcopy(scoped)
+ attach_episode_sync(
+ scoped, question="where does lib live", repo_path=root, repo_name="nogit"
+ )
+ assert scoped == before
+
+
+# -- subject scope -----------------------------------------------------------
+
+
+def test_a_subject_equal_to_the_repo_name_has_no_topic_scope(repo):
+ """Every answer in a repo names the repo, so matching on it matches nothing."""
+ _write(
+ repo,
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind="editable_shadow",
+ subject="demo",
+ body="`demo` is installed as a console script beside an editable install.",
+ evidence="Scripts/demo.exe beside a .pth",
+ nodes=(),
+ ),
+ born=time.time(),
+ )
+ before = payload(answer="Run `demo update` to refresh the demo index.", fallback_targets=[])
+
+ got = run(copy.deepcopy(before), repo, question="how do I refresh demo", name="demo")
+
+ assert got == before
+
+
+def test_a_rare_launcher_name_is_matched(repo):
+ _write(
+ repo,
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind="editable_shadow",
+ subject="demo-augment",
+ body="`demo-augment` is installed as a console script beside an editable install.",
+ evidence="Scripts/demo-augment.exe beside a .pth",
+ nodes=(),
+ ),
+ born=time.time(),
+ )
+
+ got = run(
+ payload(answer="The hook entry point is the `demo-augment` console script."),
+ repo,
+ question="what runs demo-augment",
+ name="demo",
+ )
+
+ assert got["episodes"][0]["subject"] == "demo-augment"
+
+
+def test_a_subject_matches_as_a_phrase_not_a_substring(repo):
+ _write(repo, formatter_episode(_head(repo)), born=time.time())
+ before = payload(
+ answer="The `ruff formatter` docs describe its style.", fallback_targets=[]
+ )
+
+ got = run(copy.deepcopy(before), repo, question="what is ruff formatting")
+
+ assert got == before
+
+
+# -- budget ------------------------------------------------------------------
+
+
+def test_a_long_body_is_capped_and_stays_recoverable(repo):
+ """A cap on a count is not a bound on a response whose fields are free text."""
+ long_body = "ruff drift. " * 400
+ _write(
+ repo,
+ Episode(
+ tier=TIER_STRUCTURAL,
+ kind="formatter_drift",
+ subject="ruff format",
+ body=long_body,
+ evidence="ruff format --check .",
+ nodes=(),
+ birth_commit=_head(repo),
+ ),
+ born=time.time(),
+ )
+
+ got = run(payload(), repo)
+
+ recorded = got["episodes"][0]["recorded"]
+ assert len(recorded) < len(long_body)
+ assert "repowise#" in recorded # the drop is recoverable, not silent
+ assert got["_meta"]["omitted"]["refs"]
+
+
+# -- the cached path, which is the trap --------------------------------------
+#
+# A cache hit returns long before the fresh path's payload is ever built. The
+# guard therefore runs at serve time on BOTH paths: applied before the cache
+# write instead, a disagreement would be frozen into the row and served after
+# the episode had been superseded.
+
+# Deliberately non-dominant (no gap), which is what holds the answer below
+# ``high`` — the exact calibration the live reproduction returns.
+_HITS = [
+ {"page_id": "file_page:src/auth/service.py", "score": 3.0},
+ {"page_id": "file_page:src/auth/middleware.py", "score": 2.9},
+]
+CACHE_QUESTION = "should I run ruff format before committing"
+
+
+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
+ from types import SimpleNamespace
+
+ return SimpleNamespace(content=self.content)
+
+
+async def test_the_episode_is_served_on_both_paths_and_never_cached(
+ setup_mcp, factory, monkeypatch, repo
+):
+ import json as _json
+
+ from sqlalchemy import select
+
+ import repowise.server.mcp_server as mcp_mod
+ import repowise.server.mcp_server.tool_answer.answer as answer_mod
+ from repowise.core.persistence.database import get_session
+ from repowise.core.persistence.models import AnswerCache
+ from repowise.server.mcp_server import get_answer
+
+ _write(repo, formatter_episode(_head(repo)), born=time.time())
+ monkeypatch.setattr(mcp_mod, "_repo_path", str(repo))
+ _patch_retrieval(monkeypatch, answer_mod)
+ provider = _Provider("Yes, run `ruff format` before committing to satisfy the format target.")
+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _p: provider)
+
+ fresh = await get_answer(CACHE_QUESTION)
+ assert fresh["confidence"] != "high"
+ assert fresh["episodes"][0]["kind"] == "formatter_drift"
+
+ # The cache row is the pre-episode payload: nothing to freeze, and nothing
+ # that would need an _ANSWER_SCHEMA_VERSION bump to invalidate.
+ async with get_session(factory) as session:
+ rows = list((await session.execute(select(AnswerCache))).scalars().all())
+ assert len(rows) == 1
+ assert "episodes" not in _json.loads(rows[0].payload_json)
+
+ cached = await get_answer(CACHE_QUESTION)
+ assert provider.calls == 1, "second call must be served from cache"
+ assert cached["_meta"]["cached"] is True
+ assert cached["episodes"][0]["kind"] == "formatter_drift"