Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
fix(search): stop ranking on a keyless index's own vectors (#1378)
Raghav Chamadiyabb4ccbc06827
diff --git a/packages/cli/src/repowise/cli/providers/embedders.py b/packages/cli/src/repowise/cli/providers/embedders.pyindex f61d59a34..179e040f9 100644--- a/packages/cli/src/repowise/cli/providers/embedders.py+++ b/packages/cli/src/repowise/cli/providers/embedders.py@@ -133,12 +133,12 @@ def build_embedder(embedder_name_resolved: str) -> Any:the same backend selection logic isn't duplicated. Real providers fallback to the deterministic mock when their SDK/credentials are unavailable."""- from repowise.core.providers.embedding.base import MockEmbedder+ from repowise.core.providers.embedding.base import KeylessEmbedderfrom repowise.core.providers.embedding.registry import get_embedderif embedder_name_resolved == "mock":- return MockEmbedder()+ return KeylessEmbedder()try:return get_embedder(embedder_name_resolved, **_embedder_kwargs(embedder_name_resolved))except Exception:- return MockEmbedder()+ return KeylessEmbedder()diff --git a/packages/core/src/repowise/core/analysis/decisions/semantic_match.py b/packages/core/src/repowise/core/analysis/decisions/semantic_match.pyindex 87b97789b..f75a2cd34 100644--- a/packages/core/src/repowise/core/analysis/decisions/semantic_match.py+++ b/packages/core/src/repowise/core/analysis/decisions/semantic_match.py@@ -27,6 +27,8 @@ from __future__ import annotationsimport contextlibfrom typing import Any+from repowise.core.providers.embedding.base import store_has_semantic_vectors+__all__ = ["DECISION_PAGE_TYPE","DECISION_VECTOR_PREFIX",@@ -238,7 +240,14 @@ async def find_duplicate_decision_by_vector(than the store's stale row. Same policy as the text twin: the overallnearest decision decides, thresholded at *tau*; store errors degrade tothe pending-only comparison.++ Returns None on a keyless store, without consulting *pending* either: the+ pending index holds vectors from that same embedder, so it cannot separate+ a duplicate from an unrelated record any better than the store can. See+ :func:`store_has_semantic_vectors`."""+ if not store_has_semantic_vectors(store):+ return Nonebest: tuple[str, float] | None = Nonetry:results = await store.search_by_vector(vector, limit=SEARCH_FETCH)@@ -339,9 +348,11 @@ async def find_duplicate_decision(Queries the shared store, filters hits to the ``decision:`` namespace(dropping any in *exclude_ids*), and returns the nearest one whose cosine- similarity is ≥ *tau* — or None when nothing clears the bar. Store errors- degrade to None (title dedup still applied upstream).+ similarity is ≥ *tau* — or None when nothing clears the bar. Store errors,+ and a keyless store, degrade to None (title dedup still applied upstream)."""+ if not store_has_semantic_vectors(store):+ return Nonequery = decision_match_text(title, decision)if not query:return None@@ -377,9 +388,11 @@ async def find_related_decisions(whose cosine similarity sits in the band ``[lo, hi)`` — high enough to bethe same topic, but (by default) *below* the dedup threshold so they werenot collapsed into one record. Those are exactly the candidates that might- contradict / supersede each other. Ordered best-first; store errors degrade- to an empty list.+ contradict / supersede each other. Ordered best-first; store errors, and a+ keyless store, degrade to an empty list."""+ if not store_has_semantic_vectors(store):+ return []query = decision_match_text(title, decision)if not query:return []@@ -428,11 +441,13 @@ async def find_related_decisions_many(*items* is ``(title, decision, exclude_ids)`` per query; the result listis aligned by index. Uses the store's ``search_many`` so every query isembedded in a single embedder call — the per-query network round-trip is- what made the supersession pass scale with decision count. Store errors- degrade to empty lists, matching the per-item helper.+ what made the supersession pass scale with decision count. Store errors,+ and a keyless store, degrade to empty lists, matching the per-item helper."""if not items:return []+ if not store_has_semantic_vectors(store):+ return [[] for _ in items]queries = [decision_match_text(title, decision) for title, decision, _ in items]try:# Empty query texts still occupy their slot (keeps results aligned)diff --git a/packages/core/src/repowise/core/persistence/crud/decisions.py b/packages/core/src/repowise/core/persistence/crud/decisions.pyindex 5c30e977d..9c3d4666b 100644--- a/packages/core/src/repowise/core/persistence/crud/decisions.py+++ b/packages/core/src/repowise/core/persistence/crud/decisions.py@@ -775,6 +775,7 @@ async def bulk_upsert_decisions(upsert_decision_vectors,)from repowise.core.persistence.vector_store import VectorStore+ from repowise.core.providers.embedding import store_has_semantic_vectors# Static capability check: the base-class search_by_vector is the# "unsupported" sentinel. A runtime probe would conflate a transient@@ -782,7 +783,12 @@ async def bulk_upsert_decisions(# O(N)-round-trip path this branch exists to avoid.store_cls_search = getattr(type(vector_store), "search_by_vector", None)supports_vector_search = (- callable(store_cls_search) and store_cls_search is not VectorStore.search_by_vector+ callable(store_cls_search)+ and store_cls_search is not VectorStore.search_by_vector+ # A keyless store supports the call and cannot answer it: every+ # matcher below refuses on it. Without this the batch pays for a+ # full embed round whose vectors are then never read.+ and store_has_semantic_vectors(vector_store))ordered = [diff --git a/packages/core/src/repowise/core/pipeline/phases/generation.py b/packages/core/src/repowise/core/pipeline/phases/generation.pyindex c073c1588..0d6cc9e5e 100644--- a/packages/core/src/repowise/core/pipeline/phases/generation.py+++ b/packages/core/src/repowise/core/pipeline/phases/generation.py@@ -68,7 +68,7 @@ async def run_generation(PageGenerator,)from repowise.core.persistence.vector_store import InMemoryVectorStore- from repowise.core.providers.embedding.base import MockEmbedder+ from repowise.core.providers.embedding.base import KeylessEmbedder# Attach cost tracker to LLM client if availableif cost_tracker is not None and llm_client is not None and hasattr(llm_client, "_cost_tracker"):@@ -84,7 +84,7 @@ async def run_generation(assembler = ContextAssembler(config)# Resolve embedder and vector store- embedder_impl = embedder if embedder is not None else MockEmbedder()+ embedder_impl = embedder if embedder is not None else KeylessEmbedder()if vector_store is None:vector_store = InMemoryVectorStore(embedder_impl)diff --git a/packages/core/src/repowise/core/providers/embedding/__init__.py b/packages/core/src/repowise/core/providers/embedding/__init__.pyindex d1d77770a..db0cf6d67 100644--- a/packages/core/src/repowise/core/providers/embedding/__init__.py+++ b/packages/core/src/repowise/core/providers/embedding/__init__.py@@ -11,10 +11,16 @@ registry to instantiate an embedder by name.Built-in embedders:openai — text-embedding-3-small (1536d), text-embedding-3-large (3072d)gemini — gemini-embedding-001 (768d, up to 3072d)- mock — deterministic 8d vectors (zero deps, testing only)+ mock — KeylessEmbedder: what a no-key index embeds with (zero deps)"""-from repowise.core.providers.embedding.base import Embedder, MockEmbedder+from repowise.core.providers.embedding.base import (+ Embedder,+ KeylessEmbedder,+ MockEmbedder,+ is_semantic_embedder,+ store_has_semantic_vectors,+)from repowise.core.providers.embedding.registry import (get_embedder,list_embedders,@@ -23,8 +29,11 @@ from repowise.core.providers.embedding.registry import (__all__ = ["Embedder",+ "KeylessEmbedder","MockEmbedder","get_embedder",+ "is_semantic_embedder","list_embedders","register_embedder",+ "store_has_semantic_vectors",]diff --git a/packages/core/src/repowise/core/providers/embedding/base.py b/packages/core/src/repowise/core/providers/embedding/base.pyindex fcfddc294..eea245f4d 100644--- a/packages/core/src/repowise/core/providers/embedding/base.py+++ b/packages/core/src/repowise/core/providers/embedding/base.py@@ -71,3 +71,67 @@ class MockEmbedder:norm = 1.0results.append([x / norm for x in raw])return results+++class KeylessEmbedder(MockEmbedder):+ """What an index built without an API key embeds with.++ Identical arithmetic to :class:`MockEmbedder`, and a separate type on+ purpose. The two produce the same vectors and mean opposite things:++ - In a **test**, ``MockEmbedder`` stands in for a real embedder. The suite+ wants the vector leg to run, and controls what comes back by seeding the+ store or scripting ``search``, so the vectors themselves are incidental.+ - In **production**, this class is what you get when nobody supplied a key.+ Its vectors are the only ones there are, they carry no signal, and the+ vector leg must therefore not run at all.++ One class cannot be told apart at the point that decision is made, which is+ the whole reason this one exists. Nothing else differs, and subclassing+ keeps ``isinstance(x, MockEmbedder)`` true for the width and dimension+ checks that already depend on it.++ Why the vectors carry no signal: every component is non-negative, so they+ all lie in the positive orthant of an 8-dimensional space and no two can+ point meaningfully different ways. Measured over 2,000 texts, two+ *unrelated* strings score 0.750 cosine on average, never below 0.207, and+ the nearest neighbours of any query sit at 0.926-0.962. They are distinct,+ which is what the base class promises; they are not discriminative, which+ is what a retriever needs.+ """+++def is_semantic_embedder(embedder: object) -> bool:+ """Whether *embedder* produces vectors worth ranking on.++ False for :class:`KeylessEmbedder` and for nothing else. **Deliberately+ fails open**: anything unrecognised, including ``None``, counts as semantic.++ The asymmetry is the point. This predicate exists to switch off a leg that+ is actively harmful in one identifiable configuration, so it should refuse+ only what it can positively identify. Failing closed would mean any store+ this cannot introspect loses semantic search with no error and no log line,+ which is a far worse failure than the one being fixed: it would hit custom+ and out-of-tree stores that hold a perfectly good embedder somewhere other+ than the attribute below.+ """+ return not isinstance(embedder, KeylessEmbedder)+++def store_has_semantic_vectors(store: object) -> bool:+ """Whether *store*'s vectors carry signal, i.e. whether to run its vector leg.++ Reads the embedder off the store rather than off any module-level server+ state, because workspace mode builds one context per repo through its own+ registry and factory (``core/workspace/registry.py``), so there is no single+ global that describes them all.++ Every concrete store takes an embedder as a required constructor argument+ and keeps it on ``_embedder``, so in this repo the attribute is always+ there. A store without one still returns True, per the fail-open rule in+ :func:`is_semantic_embedder`; only ``None`` is False, and that means "no+ store", not "a store that cannot rank".+ """+ if store is None:+ return False+ return is_semantic_embedder(getattr(store, "_embedder", None))diff --git a/packages/core/src/repowise/core/providers/embedding/registry.py b/packages/core/src/repowise/core/providers/embedding/registry.pyindex e74b1ddde..3e154b162 100644--- a/packages/core/src/repowise/core/providers/embedding/registry.py+++ b/packages/core/src/repowise/core/providers/embedding/registry.py@@ -28,7 +28,7 @@ _BUILTIN_EMBEDDERS: dict[str, tuple[str, str]] = {"gemini": ("repowise.core.providers.embedding.gemini", "GeminiEmbedder"),"ollama": ("repowise.core.providers.embedding.ollama", "OllamaEmbedder"),"openrouter": ("repowise.core.providers.embedding.openrouter", "OpenRouterEmbedder"),- "mock": ("repowise.core.providers.embedding.base", "MockEmbedder"),+ "mock": ("repowise.core.providers.embedding.base", "KeylessEmbedder"),}_custom_embedders: dict[str, Callable[..., Embedder]] = {}diff --git a/packages/core/src/repowise/core/workspace/registry.py b/packages/core/src/repowise/core/workspace/registry.pyindex 481539ea2..a613beea9 100644--- a/packages/core/src/repowise/core/workspace/registry.py+++ b/packages/core/src/repowise/core/workspace/registry.py@@ -169,7 +169,7 @@ class RepoRegistry:)from repowise.core.persistence.search import FullTextSearchfrom repowise.core.persistence.vector_store import InMemoryVectorStore- from repowise.core.providers.embedding.base import MockEmbedder+ from repowise.core.providers.embedding.base import KeylessEmbedderdb_url = get_db_url(f"sqlite:///{db_path.as_posix()}")@@ -188,7 +188,7 @@ class RepoRegistry:# Seed placeholder vector stores.# decision_store is repointed to the shared page store — decisions are# embedded under the "decision:" namespace, no separate LanceDB table.- embedder = self._embedder_factory() if self._embedder_factory else MockEmbedder()+ embedder = self._embedder_factory() if self._embedder_factory else KeylessEmbedder()vector_store: Any = InMemoryVectorStore(embedder=embedder)vs_ready = asyncio.Event()diff --git a/packages/server/src/repowise/server/app.py b/packages/server/src/repowise/server/app.pyindex 891d2c316..037ac7f4a 100644--- a/packages/server/src/repowise/server/app.py+++ b/packages/server/src/repowise/server/app.py@@ -27,7 +27,7 @@ from repowise.core.persistence.database import ()from repowise.core.persistence.models import GenerationJobfrom repowise.core.persistence.search import FullTextSearch-from repowise.core.providers.embedding.base import MockEmbedder+from repowise.core.providers.embedding.base import KeylessEmbedderfrom repowise.server import __version__from repowise.server.routers import (blast_radius,@@ -124,7 +124,7 @@ def _build_embedder():logger.warning("embedder.mock_active: set REPOWISE_EMBEDDER=gemini, openai, openrouter, or ollama for real RAG")- return MockEmbedder()+ return KeylessEmbedder()@asynccontextmanagerdiff --git a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.pyindex 917a89f9d..a6863b1e6 100644--- a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py+++ b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py@@ -53,6 +53,7 @@ from sqlalchemy import func, selectfrom repowise.core.analysis.decisions.semantic_match import DECISION_VECTOR_PREFIXfrom repowise.core.persistence.database import get_sessionfrom repowise.core.persistence.models import GraphEdge, GraphNode, Page+from repowise.core.providers.embedding import store_has_semantic_vectorsfrom repowise.core.test_paths import is_test_pathfrom repowise.server.mcp_server._prose_symbols import symbol_backed_pages@@ -173,8 +174,15 @@ def retrieval_legs() -> dict[str, str]:def degraded_legs(legs: dict[str, str]) -> list[str]:- """The legs that did not run, named. Empty when retrieval was whole."""- return sorted(leg for leg, outcome in legs.items() if outcome != "ok")+ """The legs that *broke*, named. Empty when retrieval was whole.++ ``keyless`` is not degradation and is deliberately excluded. A keyless index+ has no semantic vectors by construction, so its vector leg is permanently+ absent rather than transiently broken, and naming it here would put a+ failure marker on every answer the mode ever produces. The configuration+ itself is reported once per response by ``_meta`` instead.+ """+ return sorted(leg for leg, outcome in legs.items() if outcome not in ("ok", "keyless"))# Third retrieval leg: the structural symbol index. FTS and the vector store# both read the generated wiki page, which by construction carries an overview@@ -232,6 +240,9 @@ async def question_vector(ctx: Any, question: str) -> list[float] | None:store = getattr(ctx, "vector_store", None)if store is None or not question:return None+ if not store_has_semantic_vectors(store):+ # Nothing will consume it, so do not pay to compute it.+ return Nonekey = (id(store), question)cached = _QUESTION_VECTORS.get(key)@@ -282,7 +293,14 @@ async def vector_search(Every backend that can search by raw vector is spared a second embedding oftext it has already embedded; one that cannot returns None from``search_by_vector`` and is asked to search the text as before.++ Returns nothing on a keyless store. Guarded here rather than only at the+ callers because this is the shared floor under every vector read in the+ answer pipeline, and the text fallback on the last line would otherwise+ route a keyless store straight back into the embedder this is avoiding."""+ if not store_has_semantic_vectors(store):+ return []if vector is not None:by_vector = await store.search_by_vector(vector, limit=limit)if by_vector is not None:@@ -413,10 +431,19 @@ async def _safe_vector_search(ctx: Any, question: str) -> list[Any]:Also waits for vector-store readiness when the lifespan event is set —skipping the wait would race a background-loading store on cold start.++ Returns nothing on a keyless index, before the readiness wait and before the+ question is embedded: there is no vector worth computing when there is+ nothing discriminative to compare it against. See+ ``store_has_semantic_vectors``. This leg is the only entry to vector+ retrieval here, so guarding it covers every caller."""if ctx.vector_store is None:_record_leg("vector", "absent")return []+ if not store_has_semantic_vectors(ctx.vector_store):+ _record_leg("vector", "keyless")+ return []ready = getattr(ctx, "vector_store_ready", None)if ready is not None:with contextlib.suppress(TimeoutError):diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.pyindex 72224fe5b..13d6f0623 100644--- a/packages/server/src/repowise/server/mcp_server/_meta.py+++ b/packages/server/src/repowise/server/mcp_server/_meta.py@@ -337,17 +337,28 @@ def _embedder_meta() -> dict[str, Any]:agent can detect — programmatically — that semantic search is broken insteadof trusting empty/garbage retrieval. Emits nothing when the embedder ishealthy or unresolved, so healthy responses stay clean.++ A *keyless* index is a different state and gets a different field. Nothing+ is broken and nothing was misconfigured, so it is not flagged as degraded;+ but retrieval really is full-text-only, and a caller that assumes semantic+ matching is running will misread a lexical miss as "not in the codebase".+ ``semantic_search: false`` says so once per response without crying wolf."""# Lazy import: `_state` is a sibling module; importing it at call-time keeps# `_meta` free of any package import-ordering coupling.from repowise.server.mcp_server import _statestatus = getattr(_state, "_embedder_status", None)- if not status or not status.get("degraded"):+ if not status:+ return {}+ if not status.get("degraded"):+ if status.get("active") == "mock":+ return {"embedder": "mock", "semantic_search": False}return {}out: dict[str, Any] = {"embedder": status.get("active", "mock"),"embedder_degraded": True,+ "semantic_search": False,}reason = status.get("reason")if reason:diff --git a/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py b/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.pyindex f7b712962..f8ebab0e5 100644--- a/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py+++ b/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py@@ -36,6 +36,7 @@ from typing import Anyfrom sqlalchemy import selectfrom repowise.core.persistence.models import Page+from repowise.core.providers.embedding import store_has_semantic_vectorsfrom repowise.server.mcp_server._answer_pipeline import question_vector, vector_searchfrom repowise.server.mcp_server._flow_path import _is_plumbing, _load_file_adjacency@@ -165,6 +166,12 @@ async def _relevance_order("""if searcher is None or not pool:return []+ # Checked here and not only inside ``vector_search``: on a keyless index+ # ``question_vector`` returns None, which routes to the ``else`` arm below+ # and would reach the store directly, re-embedding the question on the way+ # to vectors that cannot rank. The guard has to sit above the branch.+ if not store_has_semantic_vectors(searcher):+ return []try:if vector is not None:results = await vector_search(searcher, question, _RANK_SCAN, vector=vector)diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.pyindex cb381a170..dc638bda7 100644--- a/packages/server/src/repowise/server/mcp_server/_server.py+++ b/packages/server/src/repowise/server/mcp_server/_server.py@@ -20,7 +20,7 @@ from repowise.core.persistence.database import ()from repowise.core.persistence.search import FullTextSearchfrom repowise.core.persistence.vector_store import InMemoryVectorStore-from repowise.core.providers.embedding.base import MockEmbedder+from repowise.core.providers.embedding.base import KeylessEmbedderfrom repowise.server.mcp_server import _state_log = __import__("logging").getLogger("repowise.mcp")@@ -195,7 +195,7 @@ def _resolve_embedder():"requested": name or None,"degraded": False,}- return MockEmbedder()+ return KeylessEmbedder()try:embedder = get_embedder(name, **_embedder_kwargs(name))@@ -219,7 +219,7 @@ def _resolve_embedder():"degraded": True,"reason": reason,}- return MockEmbedder()+ return KeylessEmbedder()async def _cancel_task(task: asyncio.Task) -> None:@@ -304,7 +304,7 @@ async def _load_vector_stores(repo_path: str | None) -> None:_state._decision_store = vector_storeexcept Exception:_log.exception("Failed to load vector stores — falling back to MockEmbedder")- _fallback = InMemoryVectorStore(embedder=MockEmbedder())+ _fallback = InMemoryVectorStore(embedder=KeylessEmbedder())_state._vector_store = _fallback_state._decision_store = _fallbackfinally:@@ -491,7 +491,7 @@ async def _lifespan(server: FastMCP):# Seed InMemory placeholder so tools that don't need vector search# can start immediately, before the background load completes.# decision_store is repointed to the same store — no separate table.- _placeholder = InMemoryVectorStore(embedder=MockEmbedder())+ _placeholder = InMemoryVectorStore(embedder=KeylessEmbedder())_state._vector_store = _placeholder_state._decision_store = _placeholderdiff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex f5a8d59b7..9b5b9b6e3 100644--- a/packages/server/src/repowise/server/mcp_server/tool_search.py+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py@@ -13,6 +13,7 @@ from repowise.core.persistence.models import (GitMetadata,Page,)+from repowise.core.providers.embedding import store_has_semantic_vectorsfrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.core.test_paths import is_test_path, is_test_related_pathfrom repowise.server.mcp_server._answer_pipeline import _RRF_K, _RRF_SCORE_SCALE@@ -273,11 +274,13 @@ async def _non_decision_fallback(ctx, query: str, fetch_limit: int) -> list[dict"""results = []src = "vector"- with contextlib.suppress(TimeoutError, Exception):- results = await asyncio.wait_for(- ctx.vector_store.search(query, limit=fetch_limit * 4),- timeout=8.0,- )+ # Skipped on a keyless index, which then falls through to the FTS branch.+ if store_has_semantic_vectors(ctx.vector_store):+ 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:src = "fts"with contextlib.suppress(Exception):@@ -565,8 +568,13 @@ async def _safe_vector(ctx, query: str, limit: int) -> list:Readiness is awaited by the caller (``_wait_for_vector_store``) before thefused retrieve runs, so this path does not re-wait.++ Returns nothing on a keyless index. ``store_has_semantic_vectors`` explains+ why the mock's vectors cannot be ranked on; the reason this is enforced here+ rather than in ``_fused_retrieve`` is that this function is the only place+ the vector leg is entered, so a later caller inherits the guard."""- if ctx.vector_store is None:+ if ctx.vector_store is None or not store_has_semantic_vectors(ctx.vector_store):return []with contextlib.suppress(Exception):return await asyncio.wait_for(ctx.vector_store.search(query, limit=limit), timeout=8.0)diff --git a/packages/server/src/repowise/server/mcp_server/tool_why.py b/packages/server/src/repowise/server/mcp_server/tool_why.pyindex a52372317..4e5235cb4 100644--- a/packages/server/src/repowise/server/mcp_server/tool_why.py+++ b/packages/server/src/repowise/server/mcp_server/tool_why.py@@ -18,6 +18,7 @@ from repowise.core.persistence.models import (GitMetadata,)from repowise.core.precedent.currency import describe_decision_currency+from repowise.core.providers.embedding import store_has_semantic_vectorsfrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server._budget import OmissionCollector, effective_char_budgetfrom repowise.server.mcp_server._code_rationale import mine_rationale as _mine_rationale@@ -511,10 +512,15 @@ def _rank_keyword_matches(all_decisions: list, query: str, target_set: set[str])async def _semantic_decision_results(ctx: Any, query: str) -> list:- """Semantic search of the page store, filtered to the decision: namespace."""+ """Semantic search of the page store, filtered to the decision: namespace.++ Empty on a keyless index: there is no lexical fallback here, and a window of+ arbitrary decisions is worse than none for a tool whose whole job is+ explaining why a specific thing is the way it is.+ """decision_results: list = []with contextlib.suppress(Exception):- if ctx.vector_store is not None:+ if ctx.vector_store is not None and store_has_semantic_vectors(ctx.vector_store):_raw = await ctx.vector_store.search(query, limit=50)decision_results = [r for r in _raw if getattr(r, "page_id", "").startswith(DECISION_VECTOR_PREFIX)@@ -523,11 +529,21 @@ async def _semantic_decision_results(ctx: Any, query: str) -> list:async def _semantic_doc_results(ctx: Any, query: str) -> list:- """Semantic search over documentation, falling back to FTS."""+ """Semantic search over documentation, falling back to FTS.++ A keyless index takes the FTS path directly rather than going through a+ vector store that cannot rank, which is the same answer the ``except``+ branch already produces for an unusable store.+ """+ if not store_has_semantic_vectors(getattr(ctx, "vector_store", None)):+ doc_results: list = []+ with contextlib.suppress(Exception):+ doc_results = await ctx.fts.search(query, limit=3)+ return doc_resultstry:return await ctx.vector_store.search(query, limit=3)except Exception:- doc_results: list = []+ doc_results = []with contextlib.suppress(Exception):doc_results = await ctx.fts.search(query, limit=3)return doc_resultsdiff --git a/packages/server/src/repowise/server/routers/search.py b/packages/server/src/repowise/server/routers/search.pyindex ca07a7f15..d227a07f6 100644--- a/packages/server/src/repowise/server/routers/search.py+++ b/packages/server/src/repowise/server/routers/search.py@@ -11,6 +11,7 @@ from pathlib import Pathfrom fastapi import APIRouter, Depends, Query, Request+from repowise.core.providers.embedding import store_has_semantic_vectorsfrom repowise.server.deps import (get_fts,get_vector_store,@@ -64,10 +65,19 @@ async def search(- Workspace mode without ``repo_id``: fans out across every loadedrepo's index and merges results by score."""- if search_type == "fulltext":+ # A keyless index has no semantic vectors, so a semantic request is served+ # lexically rather than refused. Returning nothing would read as "not in the+ # codebase"; returning that store's nearest neighbours would be worse still,+ # because on it they are noise. Full-text is what the mode actually offers,+ # and what the docs already promise it offers.+ if search_type == "fulltext" or not store_has_semantic_vectors(vector_store):results = await _fulltext(request, query, limit, repo_id=repo_id, primary_fts=fts)else:results = await _semantic(request, query, limit, repo_id=repo_id, primary_vs=vector_store)+ if results is None:+ # The scoped repo turned out to be keyless even though the primary+ # store is not. Serve it lexically, same as the whole-index case.+ results = await _fulltext(request, query, limit, repo_id=repo_id, primary_fts=fts)return [_to_response(r) for r in results]@@ -127,9 +137,12 @@ async def _semantic(request: Request, query: str, limit: int, *, repo_id, primarif repo_id.startswith("ws:"):return []vs = await resolve_repo_vector_store(request.app.state, repo_id)- if vs is None:- return await primary_vs.search(query, limit=limit)- return await vs.search(query, limit=limit)+ target = primary_vs if vs is None else vs+ # None, not [], so the caller can serve this repo lexically. An empty+ # list here would be indistinguishable from "nothing matched".+ if not store_has_semantic_vectors(target):+ return None+ return await target.search(query, limit=limit)if ws_config is None:# Single-repo mode. Startup resolves the primary store from the same@@ -170,7 +183,11 @@ async def _semantic(request: Request, query: str, limit: int, *, repo_id, primarvs = await resolve_repo_vector_store(request.app.state, rid)except Exception:vs = None- if vs is not None:+ # A keyless repo is skipped here rather than searched, so it reaches the+ # FTS fallback below. Its vector leg never returns empty (mock scores+ # sit near 0.75 for anything), so without this the noise window would+ # permanently suppress the fallback for that repo.+ if vs is not None and store_has_semantic_vectors(vs):try:per_repo = await vs.search(query, limit=limit)except Exception:diff --git a/packages/server/src/repowise/server/search_helpers.py b/packages/server/src/repowise/server/search_helpers.pyindex c97137b93..24dbdb153 100644--- a/packages/server/src/repowise/server/search_helpers.py+++ b/packages/server/src/repowise/server/search_helpers.py@@ -166,9 +166,9 @@ def _resolve_embedder_from_state(app_state):primary_vs = getattr(app_state, "vector_store", None)embedder = getattr(primary_vs, "_embedder", None) if primary_vs else Noneif embedder is None:- from repowise.core.providers.embedding.base import MockEmbedder+ from repowise.core.providers.embedding.base import KeylessEmbedder- embedder = MockEmbedder()+ embedder = KeylessEmbedder()return embedderdiff --git a/tests/unit/server/mcp/test_keyless_vector_leg.py b/tests/unit/server/mcp/test_keyless_vector_leg.pynew file mode 100644index 000000000..ea1711350--- /dev/null+++ b/tests/unit/server/mcp/test_keyless_vector_leg.py@@ -0,0 +1,238 @@+"""A keyless index must not rank on its own vectors.++``MockEmbedder``'s components are every one non-negative, so all of its vectors+live in the positive orthant of an 8-dimensional space and no two of them can+point meaningfully different ways: two *unrelated* strings score ~0.75 cosine on+average and never below ~0.21. They are distinct, which is what its test callers+need, and not discriminative, which is what a retriever needs.++Every documented description of the keyless mode says it is full-text-only+(``docs/reference/CONFIG.md``, ``ui/mode_selection.py``, ``init_cmd/command.py``,+``README.md``). These tests pin that.+"""++from __future__ import annotations++import asyncio+import math+import statistics+from typing import ClassVar++import pytest++from repowise.core.analysis.decisions import semantic_match+from repowise.core.persistence.vector_store.in_memory import InMemoryVectorStore+from repowise.core.providers.embedding.base import (+ KeylessEmbedder,+ MockEmbedder,+ is_semantic_embedder,+ store_has_semantic_vectors,+)+from repowise.server.mcp_server import _answer_pipeline as pipeline+from repowise.server.mcp_server import tool_search+++class _RealisticEmbedder:+ """Stand-in for a real embedder: distinct texts get distinct directions."""++ dimensions = 4++ async def embed(self, texts: list[str]) -> list[list[float]]:+ out = []+ for text in texts:+ raw = [float(text.count(c)) for c in "abcd"]+ norm = math.sqrt(sum(x * x for x in raw)) or 1.0+ out.append([x / norm for x in raw])+ return out+++class _Ctx:+ def __init__(self, store, fts=None):+ self.vector_store = store+ self.fts = fts+ self.vector_store_ready = None+++# --------------------------------------------------------------------------+# The property that motivates the whole change+# --------------------------------------------------------------------------+++def test_mock_vectors_are_not_discriminative():+ """Unrelated texts are near-identical under the mock, so ranking is noise."""+ embedder = KeylessEmbedder()+ vectors = asyncio.run(embedder.embed([f"unrelated-document-{i}" for i in range(200)]))+ pairs = [+ sum(x * y for x, y in zip(vectors[i], vectors[j], strict=True))+ for i in range(len(vectors))+ for j in range(i + 1, len(vectors))+ ]+ # Two texts with nothing in common should not look alike. Under the mock+ # they do, which is why the vector leg has to be skipped rather than+ # thresholded: there is no cutoff that separates signal from noise.+ assert statistics.mean(pairs) > 0.6+ assert min(pairs) > 0.15+++# --------------------------------------------------------------------------+# The predicate+# --------------------------------------------------------------------------+++def test_predicate_rejects_keyless_and_accepts_real():+ assert is_semantic_embedder(_RealisticEmbedder()) is True+ assert is_semantic_embedder(KeylessEmbedder()) is False+++def test_predicate_accepts_the_bare_test_double():+ """MockEmbedder stands in for a real embedder in the suite and must rank.++ The two classes share their arithmetic, so only the type separates them.+ If this ever flips, ~25 existing tests lose their vector leg silently.+ """+ assert is_semantic_embedder(MockEmbedder()) is True+ assert isinstance(KeylessEmbedder(), MockEmbedder), "width checks rely on this"+++def test_predicate_reads_the_embedder_off_the_store():+ assert store_has_semantic_vectors(InMemoryVectorStore(embedder=_RealisticEmbedder())) is True+ assert store_has_semantic_vectors(InMemoryVectorStore(embedder=KeylessEmbedder())) is False+++def test_predicate_fails_open_on_a_store_it_cannot_inspect():+ """Only positively-identified keyless stores are refused.++ Failing closed would silently disable semantic search for any store holding+ its embedder somewhere else, including out-of-tree ones. It also breaks the+ several test doubles in this suite that carry no ``_embedder`` at all.+ """+ assert store_has_semantic_vectors(object()) is True+ assert is_semantic_embedder(None) is True+ # None means "no store", which is a different thing from "cannot rank".+ assert store_has_semantic_vectors(None) is False+++# --------------------------------------------------------------------------+# search_codebase+# --------------------------------------------------------------------------+++def _seed(store, n=20):+ async def go():+ for i in range(n):+ await store.embed_and_upsert(+ f"page-{i}",+ f"page {i} about an entirely unrelated subject",+ {"title": f"Page {i}", "page_type": "file_page"},+ )++ asyncio.run(go())+ return store+++def test_search_vector_leg_is_silent_on_a_keyless_store():+ """The regression test. Fails on unfixed code, which returns a full window."""+ store = _seed(InMemoryVectorStore(embedder=KeylessEmbedder()))+ hits = asyncio.run(tool_search._safe_vector(_Ctx(store), "a totally unrelated query", 5))+ assert hits == []+++def test_search_vector_leg_still_runs_on_a_real_store():+ store = _seed(InMemoryVectorStore(embedder=_RealisticEmbedder()))+ hits = asyncio.run(tool_search._safe_vector(_Ctx(store), "aaa bbb", 5))+ assert hits, "a real embedder must still retrieve"+++def test_fused_retrieve_returns_nothing_when_keyless_and_fts_misses():+ """Keyless + no lexical match must mean no results, not nearest neighbours."""++ class _EmptyFts:+ async def search(self, query, limit=10):+ return []++ store = _seed(InMemoryVectorStore(embedder=KeylessEmbedder()))+ out = asyncio.run(+ tool_search._fused_retrieve(_Ctx(store, _EmptyFts()), "unrelated query", 15, None)+ )+ assert out == []+++# --------------------------------------------------------------------------+# get_answer+# --------------------------------------------------------------------------+++def test_answer_vector_leg_is_silent_and_says_why():+ store = _seed(InMemoryVectorStore(embedder=KeylessEmbedder()))+ pipeline.begin_leg_record()+ hits = asyncio.run(pipeline._safe_vector_search(_Ctx(store), "an unrelated question"))+ assert hits == []+ assert pipeline.retrieval_legs()["vector"] == "keyless"+++def test_keyless_is_reported_but_not_as_a_failure():+ """A permanent configuration is not a leg that fell over."""+ assert pipeline.degraded_legs({"fts": "ok", "vector": "keyless"}) == []+ assert pipeline.degraded_legs({"fts": "ok", "vector": "timeout"}) == ["vector"]+++# --------------------------------------------------------------------------+# Decision dedup+# --------------------------------------------------------------------------++[email protected]("n_existing", [10, 60])+def test_dedup_refuses_rather_than_guessing_on_a_keyless_store(n_existing):+ """Unfixed, this merges an unrelated decision ~100% of the time at n=60."""+ store = InMemoryVectorStore(embedder=KeylessEmbedder())++ async def go():+ for i in range(n_existing):+ await store.embed_and_upsert(+ f"{semantic_match.DECISION_VECTOR_PREFIX}d{i}",+ f"decision {i} on an entirely separate topic",+ {"title": f"Decision {i}"},+ )+ return await semantic_match.find_duplicate_decision(+ store, title="A brand new and unrelated decision"+ )++ assert asyncio.run(go()) is None+++def test_related_decisions_are_empty_on_a_keyless_store():+ store = InMemoryVectorStore(embedder=KeylessEmbedder())++ async def go():+ for i in range(30):+ await store.embed_and_upsert(+ f"{semantic_match.DECISION_VECTOR_PREFIX}d{i}",+ f"decision {i}",+ {"title": f"Decision {i}"},+ )+ single = await semantic_match.find_related_decisions(store, title="Unrelated", lo=0.5)+ many = await semantic_match.find_related_decisions_many(+ store, [("Unrelated", "", set()), ("Also unrelated", "", set())], lo=0.5+ )+ return single, many++ single, many = asyncio.run(go())+ assert single == []+ assert many == [[], []]+++def test_dedup_by_vector_ignores_the_pending_index_too():+ """Pending vectors come from the same embedder, so they are equally blind."""+ store = InMemoryVectorStore(embedder=KeylessEmbedder())+ vector = asyncio.run(KeylessEmbedder().embed(["a new decision"]))[0]++ class _Pending:+ ids: ClassVar[set[str]] = {"decision:other"}++ def best(self, _v):+ return ("decision:other", 0.99)++ got = asyncio.run(+ semantic_match.find_duplicate_decision_by_vector(store, vector, pending=_Pending())+ )+ assert got is None