kiri-mcp-server 0.11.0 → 0.13.0

package/dist/src/server/handlers.js

@@ -1,10 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { checkFTSSchemaExists } from "../indexer/schema.js";
+import { getAdaptiveK } from "../shared/adaptive-k.js";
 import { generateEmbedding, structuralSimilarity } from "../shared/embedding.js";
 import { encode as encodeGPT, tokenizeText } from "../shared/tokenizer.js";
 import { expandAbbreviations } from "./abbreviations.js";
 import { getBoostProfile, } from "./boost-profiles.js";
+import { loadPathPenalties, mergePathPenaltyEntries } from "./config-loader.js";
 import { loadServerConfig } from "./config.js";
 import { coerceProfileName, loadScoringProfile } from "./scoring.js";
 import { createServerServices } from "./services/index.js";
@@ -336,6 +338,76 @@ function bucketArtifactHints(hints) {
     }
     return buckets;
 }
+function selectDomainPathHints(hints) {
+    const selected = [];
+    for (const hint of hints) {
+        if (!SAFE_PATH_PATTERN.test(hint.path)) {
+            continue;
+        }
+        if (selected.some((entry) => entry.path === hint.path)) {
+            continue;
+        }
+        selected.push(hint);
+        if (selected.length >= DOMAIN_PATH_HINT_LIMIT) {
+            break;
+        }
+    }
+    return selected;
+}
+/**
+ * AdaptiveK用カテゴリ自動検出
+ *
+ * 優先順位:
+ * 1. params.categoryが明示的に指定されている場合はそれを使用
+ * 2. profile/artifacts/boost_profileから推論
+ *
+ * @param params - context_bundleのパラメータ
+ * @returns 検出されたカテゴリ（undefined = デフォルトK値を使用）
+ */
+function determineCategory(params) {
+    // 明示的に指定されている場合はそれを優先
+    if (params.category) {
+        return params.category;
+    }
+    const { profile, boost_profile, artifacts } = params;
+    // artifacts.failing_testsがある場合はデバッグ作業
+    if (artifacts?.failing_tests && artifacts.failing_tests.length > 0) {
+        return "debug";
+    }
+    // profileからの推論
+    if (profile === "testfail") {
+        return "testfail";
+    }
+    if (profile === "bugfix" || profile === "typeerror") {
+        return "debug";
+    }
+    if (profile === "refactor") {
+        return "api";
+    }
+    if (profile === "feature") {
+        return "feature";
+    }
+    // boost_profileからの推論
+    if (boost_profile === "docs") {
+        return "docs";
+    }
+    // artifacts.editing_pathからの推論
+    if (artifacts?.editing_path) {
+        const editingPath = artifacts.editing_path.toLowerCase();
+        // テストファイルを編集中 → debug
+        if (editingPath.includes(".test.") ||
+            editingPath.includes(".spec.") ||
+            editingPath.includes("__tests__")) {
+            return "debug";
+        }
+        // ドキュメントを編集中 → docs
+        if (editingPath.endsWith(".md") || editingPath.includes("/docs/")) {
+            return "docs";
+        }
+    }
+    // 推論できない場合はundefined（kDefaultを使用）
+    return undefined;
+}
 function isMissingTableError(error, table) {
     if (!(error instanceof Error)) {
         return false;
@@ -447,22 +519,34 @@ function createHintExpansionConfig(weights) {
 const DEFAULT_SEARCH_LIMIT = 50;
 const DEFAULT_BUNDLE_LIMIT = 7; // Reduced from 12 to optimize token usage
 const MAX_BUNDLE_LIMIT = 20;
+const TRACE_SEARCH = process.env.KIRI_TRACE_SEARCH === "1";
 const MAX_KEYWORDS = 12;
 const MAX_MATCHES_PER_KEYWORD = 40;
 const MAX_DEPENDENCY_SEEDS = 8;
 const MAX_DEPENDENCY_SEEDS_QUERY_LIMIT = 100; // SQL injection防御用の上限
 const NEARBY_LIMIT = 6;
 const serverConfig = loadServerConfig();
+const mergedPathMultiplierCache = new Map();
 const SUPPRESS_NON_CODE_ENABLED = serverConfig.features.suppressNonCode;
 const FINAL_RESULT_SUPPRESSION_ENABLED = serverConfig.features.suppressFinalResults;
 const CLAMP_SNIPPETS_ENABLED = serverConfig.features.clampSnippets;
 const FALLBACK_SNIPPET_WINDOW = serverConfig.features.snippetWindow;
 const MAX_RERANK_LIMIT = 50;
 const MAX_ARTIFACT_HINTS = 8;
+const DOMAIN_PATH_HINT_LIMIT = MAX_ARTIFACT_HINTS;
 const SAFE_PATH_PATTERN = /^[a-zA-Z0-9_.\-/]+$/;
 const HINT_PRIORITY_TEXT_MULTIPLIER = serverConfig.hints.priority.textMultiplier;
 const HINT_PRIORITY_PATH_MULTIPLIER = serverConfig.hints.priority.pathMultiplier;
 const HINT_PRIORITY_BASE_BONUS = serverConfig.hints.priority.baseBonus;
+const PATH_FALLBACK_LIMIT = 40;
+const PATH_FALLBACK_TERMS_LIMIT = 5;
+const PATH_FALLBACK_KEEP = 8;
+const AUTO_PATH_SEGMENT_LIMIT = 4;
+function traceSearch(message, ...args) {
+    if (TRACE_SEARCH) {
+        console.log(`[TRACE context_bundle] ${message}`, ...args);
+    }
+}
 const HINT_DIR_LIMIT = serverConfig.hints.directory.limit;
 const HINT_DIR_MAX_FILES = serverConfig.hints.directory.maxFiles;
 const HINT_DEP_OUT_LIMIT = serverConfig.hints.dependency.outLimit;
@@ -811,8 +895,30 @@ function extractKeywords(text) {
             }
         }
     }
+    addKeywordDerivedPathSegments(result);
     return result;
 }
+function addKeywordDerivedPathSegments(result) {
+    if (result.pathSegments.length >= AUTO_PATH_SEGMENT_LIMIT) {
+        return;
+    }
+    const additional = [];
+    for (const keyword of result.keywords) {
+        if (keyword.length < 3 || STOP_WORDS.has(keyword)) {
+            continue;
+        }
+        if (result.pathSegments.includes(keyword) || additional.includes(keyword)) {
+            continue;
+        }
+        additional.push(keyword);
+        if (result.pathSegments.length + additional.length >= AUTO_PATH_SEGMENT_LIMIT) {
+            break;
+        }
+    }
+    if (additional.length > 0) {
+        result.pathSegments.push(...additional);
+    }
+}
 function ensureCandidate(map, filePath) {
     let candidate = map.get(filePath);
     if (!candidate) {
@@ -829,12 +935,35 @@ function ensureCandidate(map, filePath) {
             embedding: null,
             semanticSimilarity: null,
             pathMatchHits: 0, // Issue #68: Track path match count
+            keywordHits: new Set(),
+            phraseHits: 0,
+            // pathFallbackReason は optional なので省略（exactOptionalPropertyTypes対応）
+            fallbackTextHits: 0,
             penalties: [], // Issue #68: Penalty log for telemetry
         };
         map.set(filePath, candidate);
     }
     return candidate;
 }
+function normalizePathPrefix(rawPrefix) {
+    // Normalize, strip leading slashes/dots, and ensure trailing slash for exact prefix match
+    const normalized = path.posix.normalize(rawPrefix.replace(/\\/g, "/"));
+    const stripped = normalized.replace(/^\.\//, "").replace(/^\/+/, "");
+    if (stripped === "" || stripped === ".") {
+        return "";
+    }
+    return stripped.endsWith("/") ? stripped : `${stripped}/`;
+}
+function normalizeFilePath(filePath) {
+    return path.posix.normalize(filePath.replace(/\\/g, "/")).replace(/^\/+/, "");
+}
+function pathMatchesPrefix(filePath, normalizedPrefix) {
+    if (!normalizedPrefix) {
+        return true;
+    }
+    const normalizedPath = normalizeFilePath(filePath);
+    return normalizedPath.startsWith(normalizedPrefix);
+}
 async function expandHintCandidatesForHints(params) {
     const { hintPaths, config } = params;
     if (hintPaths.length === 0 || config.perHintLimit <= 0 || config.dbQueryBudget <= 0) {
@@ -1537,13 +1666,17 @@ async function safeLinkQuery(db, tableAvailability, sql, params) {
         throw error;
     }
 }
-async function fetchMetadataOnlyCandidates(db, tableAvailability, repoId, filters, limit) {
+async function fetchMetadataOnlyCandidates(db, tableAvailability, repoId, filters, limit, pathPrefix) {
     if (!tableAvailability.hasMetadataTables || filters.length === 0 || limit <= 0) {
         return [];
     }
     const filterClauses = buildMetadataFilterConditions(filters);
     const whereClauses = ["f.repo_id = ?"];
     const params = [repoId];
+    if (pathPrefix) {
+        whereClauses.push("f.path LIKE ?");
+        params.push(`${pathPrefix}%`);
+    }
     for (const clause of filterClauses) {
         whereClauses.push(clause.sql);
         params.push(...clause.params);
@@ -1568,13 +1701,17 @@ async function fetchMetadataOnlyCandidates(db, tableAvailability, repoId, filter
         throw error;
     }
 }
-async function fetchMetadataKeywordMatches(db, tableAvailability, repoId, keywords, filters, limit, excludePaths) {
+async function fetchMetadataKeywordMatches(db, tableAvailability, repoId, keywords, filters, limit, excludePaths, pathPrefix) {
     if (!tableAvailability.hasMetadataTables || keywords.length === 0 || limit <= 0) {
         return [];
     }
     const keywordClauses = keywords.map(() => "mk.value ILIKE ?").join(" OR ");
     const params = [repoId, ...keywords.map((kw) => `%${kw}%`)];
     const whereClauses = ["mk.repo_id = ?", `(${keywordClauses})`];
+    if (pathPrefix) {
+        whereClauses.push("f.path LIKE ?");
+        params.push(`${pathPrefix}%`);
+    }
     if (excludePaths.size > 0) {
         const placeholders = Array.from(excludePaths)
             .map(() => "?")
@@ -1774,6 +1911,50 @@ function applyFileTypeBoost(path, baseScore, profileConfig, weights) {
     }
     return baseScore * multiplier;
 }
+function applyCoverageBoost(candidate, extractedTerms, weights) {
+    // Skip for pure path-fallback candidates without text evidence
+    if (candidate.reasons.has("fallback:path") &&
+        candidate.keywordHits.size === 0 &&
+        candidate.phraseHits === 0) {
+        return;
+    }
+    // Coverage boost is only meaningful for text/phrase evidence; skip if no text evidence at all
+    if (candidate.keywordHits.size === 0 && candidate.phraseHits === 0) {
+        return;
+    }
+    if (extractedTerms.keywords.length > 0 && candidate.keywordHits.size > 0) {
+        const coverage = candidate.keywordHits.size / extractedTerms.keywords.length;
+        const bonus = coverage * weights.textMatch * 0.4;
+        candidate.score += bonus;
+        candidate.reasons.add(`coverage:keywords:${coverage.toFixed(2)}`);
+    }
+    if (extractedTerms.phrases.length > 0 && candidate.phraseHits > 0) {
+        const phraseCoverage = Math.min(1, candidate.phraseHits / extractedTerms.phrases.length);
+        const bonus = phraseCoverage * weights.textMatch * 0.6;
+        candidate.score += bonus;
+        candidate.reasons.add(`coverage:phrases:${phraseCoverage.toFixed(2)}`);
+    }
+}
+async function fetchPathFallbackCandidates(db, repoId, terms, limit) {
+    if (terms.length === 0 || limit <= 0) {
+        return [];
+    }
+    const filters = terms.map(() => "f.path ILIKE ?").join(" OR ");
+    const params = [repoId, ...terms.map((term) => `%${term}%`), limit];
+    return await db.all(`
+      SELECT f.path, f.lang, f.ext, f.is_binary, b.content, fe.vector_json, fe.dims AS vector_dims
+      FROM file f
+      JOIN blob b ON b.hash = f.blob_hash
+      LEFT JOIN file_embedding fe
+        ON fe.repo_id = f.repo_id
+       AND fe.path = f.path
+      WHERE f.repo_id = ?
+        AND f.is_binary = FALSE
+        AND (${filters})
+      ORDER BY f.path
+      LIMIT ?
+    `, params);
+}
 /**
  * パスベースのスコアリングを適用（加算的ブースト）
  * goalのキーワード/フレーズがファイルパスに含まれる場合にスコアを加算
@@ -1955,6 +2136,18 @@ function applyMultiplicativeFilePenalties(candidate, path, lowerPath, fileName,
 function applyFileTypeMultipliers(candidate, path, ext, profileConfig, weights) {
     const fileName = path.split("/").pop() ?? "";
     const lowerPath = path.toLowerCase();
+    // Very low value: schemas, fixtures, testdata, examples, baseline
+    const schemaJson = lowerPath.endsWith(".schema.json") || lowerPath.includes("/schemas/");
+    const isFixture = lowerPath.includes("/fixtures/") ||
+        lowerPath.includes("/fixture/") ||
+        lowerPath.includes("/testdata/");
+    const isExample = lowerPath.includes("/examples/") || lowerPath.includes("/example/");
+    const isBaseline = lowerPath.includes("baseline") || lowerPath.includes("golden");
+    if (schemaJson || isFixture || isExample || isBaseline) {
+        candidate.scoreMultiplier *= weights.configPenaltyMultiplier;
+        candidate.reasons.add("penalty:low-value-file");
+        return;
+    }
     // ✅ Step 1: Low-value files (v1.0.0: syntax/perf/legal/migration)
     // Apply configPenaltyMultiplier (strong penalty) to rarely useful file types
     const isSyntaxGrammar = path.includes("/syntaxes/") &&
@@ -2072,6 +2265,7 @@ export async function filesSearch(context, params) {
         cleanedQuery = cleanedQuery.trim();
         hasTextQuery = cleanedQuery.length > 0;
     }
+    const pathPrefix = params.path_prefix && params.path_prefix.length > 0 ? params.path_prefix : undefined;
     const metadataValueSeed = metadataFilters
         .flatMap((filter) => filter.values)
         .map((value) => value.trim())
@@ -2170,7 +2364,7 @@ export async function filesSearch(context, params) {
         candidateRows.push(...textRows);
     }
     if (!hasTextQuery && hasAnyMetadataFilters) {
-        const metadataOnlyRows = await fetchMetadataOnlyCandidates(db, context.tableAvailability, repoId, metadataFilters, limit * 2);
+        const metadataOnlyRows = await fetchMetadataOnlyCandidates(db, context.tableAvailability, repoId, metadataFilters, limit * 2, pathPrefix);
         for (const row of metadataOnlyRows) {
             row.score = 1 + metadataFilters.length * 0.2;
         }
@@ -2180,7 +2374,7 @@ export async function filesSearch(context, params) {
         const metadataKeywords = splitQueryWords(cleanedQuery.toLowerCase()).map((kw) => kw.toLowerCase());
         if (metadataKeywords.length > 0) {
             const excludePaths = new Set(candidateRows.map((row) => row.path));
-            const metadataRows = await fetchMetadataKeywordMatches(db, context.tableAvailability, repoId, metadataKeywords, metadataFilters, limit * 2, excludePaths);
+            const metadataRows = await fetchMetadataKeywordMatches(db, context.tableAvailability, repoId, metadataKeywords, metadataFilters, limit * 2, excludePaths, pathPrefix);
             candidateRows.push(...metadataRows);
         }
     }
@@ -2207,7 +2401,17 @@ export async function filesSearch(context, params) {
     const filterValueSet = new Set(metadataFilters.flatMap((filter) => filter.values.map((value) => value.toLowerCase())));
     const boostProfile = params.boost_profile ??
         (hasHintMetadataFilters ? "balanced" : hasStrictMetadataFilters ? "docs" : "default");
-    const profileConfig = getBoostProfile(boostProfile);
+    const baseProfileConfig = getBoostProfile(boostProfile);
+    const cachedMerged = mergedPathMultiplierCache.get(boostProfile);
+    const mergedPathMultipliers = cachedMerged ??
+        mergePathPenaltyEntries(baseProfileConfig.pathMultipliers, [], serverConfig.pathPenalties);
+    if (!cachedMerged) {
+        mergedPathMultiplierCache.set(boostProfile, mergedPathMultipliers);
+    }
+    const profileConfig = {
+        ...baseProfileConfig,
+        pathMultipliers: mergedPathMultipliers,
+    };
     const weights = loadScoringProfile(null);
     const options = parseOutputOptions(params);
     const previewQuery = hasTextQuery
@@ -2543,7 +2747,22 @@ async function contextBundleImpl(context, params) {
             mergedFilters: metadataFilters,
         }));
     }
-    const limit = normalizeBundleLimit(params.limit);
+    // AdaptiveK: カテゴリに基づいてK値を動的に調整
+    // 1. params.categoryが明示的に指定されていればそれを使用
+    // 2. そうでなければprofile/artifacts/boost_profileから自動検出
+    const detectedCategory = determineCategory(params);
+    const adaptiveK = getAdaptiveK(detectedCategory, serverConfig.adaptiveK);
+    const adaptiveLimit = normalizeBundleLimit(adaptiveK);
+    const requestedLimit = normalizeBundleLimit(params.limit);
+    // AdaptiveKが無効な場合はrequestLimitをそのまま使用
+    // AdaptiveKが有効な場合:
+    //   - ユーザー指定limitがなければadaptiveKを使用
+    //   - ユーザー指定がある場合は小さい方を採用（過剰取得防止）
+    const limit = serverConfig.adaptiveK.enabled
+        ? params.limit === undefined
+            ? adaptiveLimit
+            : Math.min(requestedLimit, adaptiveLimit)
+        : requestedLimit;
     const artifacts = params.artifacts ?? {};
     const artifactHints = normalizeArtifactHints(artifacts.hints);
     const hintBuckets = bucketArtifactHints(artifactHints);
@@ -2551,6 +2770,9 @@ async function contextBundleImpl(context, params) {
     const substringHints = hintBuckets.substringHints;
     const includeTokensEstimate = params.includeTokensEstimate === true;
     const isCompact = params.compact === true;
+    const pathPrefix = params.path_prefix && params.path_prefix.length > 0
+        ? normalizePathPrefix(params.path_prefix)
+        : undefined;
     // 項目2: トークンバジェット保護警告
     // 大量データ+非コンパクトモード+トークン推定なしの場合に警告
     // リクエストごとに警告（warnForRequestを使用）
@@ -2580,9 +2802,18 @@ async function contextBundleImpl(context, params) {
             .join(" ");
         keywordSources.push(filterSeed);
     }
+    const baseSeed = keywordSources.join(" ");
+    const domainExpansion = process.env.KIRI_ENABLE_DOMAIN_TERMS === "1"
+        ? context.services.domainTerms.expandFromText(baseSeed)
+        : { matched: [], aliases: [], fileHints: [] };
+    if (domainExpansion.aliases.length > 0) {
+        keywordSources.push(domainExpansion.aliases.join(" "));
+    }
     const semanticSeed = keywordSources.join(" ");
     const queryEmbedding = generateEmbedding(semanticSeed)?.values ?? null;
     const extractedTerms = extractKeywords(semanticSeed);
+    const segmentPreview = extractedTerms.pathSegments.slice(0, AUTO_PATH_SEGMENT_LIMIT).join(",");
+    traceSearch(`terms repo=${repoId} id=${params.requestId ?? "n/a"} keywords=${extractedTerms.keywords.length} phrases=${extractedTerms.phrases.length} pathSegments=${extractedTerms.pathSegments.length} segs=[${segmentPreview}]`);
     // フォールバック: editing_pathからキーワードを抽出
     if (extractedTerms.phrases.length === 0 &&
         extractedTerms.keywords.length === 0 &&
@@ -2599,14 +2830,24 @@ async function contextBundleImpl(context, params) {
     // ✅ Cache boost profile config to avoid redundant lookups in hot path
     const boostProfile = params.boost_profile ??
         (hasHintMetadataFilters ? "balanced" : hasStrictMetadataFilters ? "docs" : "default");
-    const profileConfig = getBoostProfile(boostProfile);
+    const baseProfileConfig = getBoostProfile(boostProfile);
+    const profileConfig = {
+        ...baseProfileConfig,
+        pathMultipliers: loadPathPenalties(baseProfileConfig.pathMultipliers),
+    };
     // フレーズマッチング（高い重み: textMatch × 2）- 統合クエリでパフォーマンス改善
     if (extractedTerms.phrases.length > 0) {
         const phrasePlaceholders = extractedTerms.phrases
             .map(() => "b.content ILIKE '%' || ? || '%'")
             .join(" OR ");
         // DEBUG: Log SQL query parameters for troubleshooting
-        console.log(`[DEBUG contextBundle] Executing phrase match query with repo_id=${repoId}, phrases=${JSON.stringify(extractedTerms.phrases)}`);
+        traceSearch(`Executing phrase match query with repo_id=${repoId}, phrases=${JSON.stringify(extractedTerms.phrases)}`);
+        const phraseWhereClauses = ["f.repo_id = ?", "f.is_binary = FALSE", `(${phrasePlaceholders})`];
+        const phraseParams = [repoId, ...extractedTerms.phrases];
+        if (pathPrefix) {
+            phraseWhereClauses.push("f.path LIKE ?");
+            phraseParams.push(`${pathPrefix}%`);
+        }
         const rows = await db.all(`
         SELECT f.path, f.lang, f.ext, f.is_binary, b.content, fe.vector_json, fe.dims AS vector_dims
         FROM file f
@@ -2614,19 +2855,21 @@ async function contextBundleImpl(context, params) {
         LEFT JOIN file_embedding fe
           ON fe.repo_id = f.repo_id
          AND fe.path = f.path
-        WHERE f.repo_id = ?
-          AND f.is_binary = FALSE
-          AND (${phrasePlaceholders})
+        WHERE ${phraseWhereClauses.join(`
+          AND `)}
         ORDER BY f.path
         LIMIT ?
-      `, [repoId, ...extractedTerms.phrases, MAX_MATCHES_PER_KEYWORD * extractedTerms.phrases.length]);
+      `, [...phraseParams, MAX_MATCHES_PER_KEYWORD * extractedTerms.phrases.length]);
         // DEBUG: Log returned paths and verify they match expected repo_id
         if (rows.length > 0) {
-            console.log(`[DEBUG contextBundle] Phrase match returned ${rows.length} rows. Sample paths:`, rows.slice(0, 3).map((r) => r.path));
+            traceSearch(`Phrase match returned ${rows.length} rows. Sample paths: ${rows
+                .slice(0, 3)
+                .map((r) => r.path)
+                .join(", ")}`);
             // Verify repo_id of returned files
             const pathsToCheck = rows.slice(0, 3).map((r) => r.path);
             const verification = await db.all(`SELECT path, repo_id FROM file WHERE path IN (${pathsToCheck.map(() => "?").join(", ")}) LIMIT 3`, pathsToCheck);
-            console.log(`[DEBUG contextBundle] Repo ID verification:`, verification);
+            traceSearch(`Repo ID verification`, verification);
         }
         for (const row of rows) {
             if (row.content === null) {
@@ -2639,6 +2882,7 @@ async function contextBundleImpl(context, params) {
                 continue; // Should not happen, but defensive check
             }
             const candidate = ensureCandidate(candidates, row.path);
+            candidate.phraseHits += matchedPhrases.length;
             // 各マッチしたフレーズに対してスコアリング
             for (const phrase of matchedPhrases) {
                 // フレーズマッチは通常の2倍のスコア
@@ -2669,12 +2913,23 @@ async function contextBundleImpl(context, params) {
                 });
             }
         }
+        traceSearch(`phrase search produced ${rows.length} rows, candidates=${candidates.size}`);
     }
     // キーワードマッチング（通常の重み）- 統合クエリでパフォーマンス改善
     if (extractedTerms.keywords.length > 0) {
         const keywordPlaceholders = extractedTerms.keywords
             .map(() => "b.content ILIKE '%' || ? || '%'")
             .join(" OR ");
+        const keywordWhereClauses = [
+            "f.repo_id = ?",
+            "f.is_binary = FALSE",
+            `(${keywordPlaceholders})`,
+        ];
+        const keywordParams = [repoId, ...extractedTerms.keywords];
+        if (pathPrefix) {
+            keywordWhereClauses.push("f.path LIKE ?");
+            keywordParams.push(`${pathPrefix}%`);
+        }
         const rows = await db.all(`
         SELECT f.path, f.lang, f.ext, f.is_binary, b.content, fe.vector_json, fe.dims AS vector_dims
         FROM file f
@@ -2682,12 +2937,11 @@ async function contextBundleImpl(context, params) {
         LEFT JOIN file_embedding fe
           ON fe.repo_id = f.repo_id
          AND fe.path = f.path
-        WHERE f.repo_id = ?
-          AND f.is_binary = FALSE
-          AND (${keywordPlaceholders})
+        WHERE ${keywordWhereClauses.join(`
+          AND `)}
         ORDER BY f.path
         LIMIT ?
-      `, [repoId, ...extractedTerms.keywords, MAX_MATCHES_PER_KEYWORD * extractedTerms.keywords.length]);
+      `, [...keywordParams, MAX_MATCHES_PER_KEYWORD * extractedTerms.keywords.length]);
         for (const row of rows) {
             if (row.content === null) {
                 continue;
@@ -2703,6 +2957,7 @@ async function contextBundleImpl(context, params) {
             for (const keyword of matchedKeywords) {
                 candidate.score += weights.textMatch;
                 candidate.reasons.add(`text:${keyword}`);
+                candidate.keywordHits.add(keyword);
             }
             // Apply boost profile once per file
             if (boostProfile !== "none") {
@@ -2728,15 +2983,114 @@ async function contextBundleImpl(context, params) {
                 });
             }
         }
+        traceSearch(`keyword search produced ${rows.length} rows, candidates=${candidates.size}`);
+    }
+    const fallbackTerms = Array.from(new Set([...extractedTerms.phrases, ...extractedTerms.keywords, ...extractedTerms.pathSegments]
+        .map((term) => term.toLowerCase())
+        .filter((term) => term.length >= 3))).slice(0, PATH_FALLBACK_TERMS_LIMIT);
+    if (fallbackTerms.length > 0) {
+        const fallbackRows = await fetchPathFallbackCandidates(db, repoId, fallbackTerms, Math.min(limit * 2, PATH_FALLBACK_LIMIT));
+        const fallbackReason = stringMatchSeeds.size === 0
+            ? "no-string-match"
+            : candidates.size < limit
+                ? "low-candidates"
+                : "supplemental";
+        traceSearch(`path fallback triggered (${fallbackReason}) terms=${JSON.stringify(fallbackTerms)} rows=${fallbackRows.length}`);
+        const fallbackWeight = stringMatchSeeds.size === 0 ? weights.pathMatch * 0.75 : weights.pathMatch * 0.2;
+        for (const row of fallbackRows) {
+            const candidate = ensureCandidate(candidates, row.path);
+            candidate.pathFallbackReason = fallbackReason;
+            candidate.score += fallbackWeight;
+            candidate.reasons.add("fallback:path");
+            const contentLower = row.content?.toLowerCase() ?? "";
+            if (contentLower.length > 0) {
+                let textHits = 0;
+                for (const term of fallbackTerms) {
+                    if (contentLower.includes(term)) {
+                        textHits += 1;
+                        candidate.keywordHits.add(term);
+                    }
+                }
+                candidate.fallbackTextHits += textHits;
+                if (textHits > 0) {
+                    const textBoost = textHits * weights.textMatch * 0.15;
+                    candidate.score += textBoost;
+                    candidate.reasons.add(`fallback:content:${textHits}`);
+                }
+            }
+            candidate.matchLine ??= 1;
+            candidate.lang ??= row.lang;
+            candidate.ext ??= row.ext;
+            candidate.totalLines ??= row.content?.split(/\r?\n/).length ?? null;
+            candidate.content ??= row.content;
+            candidate.embedding ??= parseEmbedding(row.vector_json ?? null, row.vector_dims ?? null);
+            if (boostProfile !== "none") {
+                applyBoostProfile(candidate, row, profileConfig, weights, extractedTerms);
+            }
+            stringMatchSeeds.add(row.path);
+            if (!fileCache.has(row.path) && row.content) {
+                fileCache.set(row.path, {
+                    content: row.content,
+                    lang: row.lang,
+                    ext: row.ext,
+                    totalLines: candidate.totalLines ?? 0,
+                    embedding: candidate.embedding,
+                });
+            }
+        }
+        // Drop fallback-only candidates with zero text evidence before trimming
+        for (const [path, candidate] of Array.from(candidates.entries())) {
+            const isFallbackOnly = candidate.reasons.has("fallback:path") &&
+                candidate.keywordHits.size === 0 &&
+                candidate.phraseHits === 0;
+            const hasTextEvidence = candidate.fallbackTextHits > 0;
+            if (isFallbackOnly && !hasTextEvidence) {
+                candidates.delete(path);
+            }
+        }
+        // Demote fallback-only hits without text evidence
+        for (const candidate of candidates.values()) {
+            const isFallbackOnly = candidate.reasons.has("fallback:path") &&
+                candidate.keywordHits.size === 0 &&
+                candidate.phraseHits === 0;
+            const hasTextEvidence = candidate.fallbackTextHits > 0;
+            if (isFallbackOnly && !hasTextEvidence) {
+                candidate.scoreMultiplier *= 0.5;
+                candidate.reasons.add("penalty:fallback-no-text");
+            }
+        }
+        if (fallbackRows.length > PATH_FALLBACK_KEEP) {
+            const fallbackOnly = Array.from(candidates.entries())
+                .filter(([_, candidate]) => candidate.reasons.has("fallback:path") &&
+                candidate.keywordHits.size === 0 &&
+                candidate.phraseHits === 0)
+                .sort((a, b) => b[1].score - a[1].score);
+            const toDrop = fallbackOnly.slice(PATH_FALLBACK_KEEP);
+            for (const [path] of toDrop) {
+                candidates.delete(path);
+            }
+            traceSearch(`path fallback trimmed kept=${PATH_FALLBACK_KEEP} dropped=${toDrop.length} candidates=${candidates.size}`);
+        }
+    }
+    if (extractedTerms.keywords.length > 0 || extractedTerms.phrases.length > 0) {
+        for (const candidate of candidates.values()) {
+            applyCoverageBoost(candidate, extractedTerms, weights);
+        }
     }
     const artifactPathTargets = artifactPathHints.map((hintPath) => ({
         path: hintPath,
         sourceHint: hintPath,
         origin: "artifact",
     }));
+    const domainPathTargets = selectDomainPathHints(domainExpansion.fileHints).map((hint) => ({
+        path: hint.path,
+        sourceHint: hint.source,
+        origin: "dictionary",
+    }));
     const dictionaryPathTargets = await fetchDictionaryPathHints(db, context.tableAvailability, repoId, substringHints, HINT_DICTIONARY_LIMIT);
     const { list: resolvedPathHintTargets, meta: hintSeedMeta } = createHintSeedMeta([
         ...artifactPathTargets,
+        ...domainPathTargets,
         ...dictionaryPathTargets,
     ]);
     if (resolvedPathHintTargets.length > 0) {
@@ -2831,6 +3185,9 @@ async function contextBundleImpl(context, params) {
     const materializeCandidates = async () => {
         const result = [];
         for (const candidate of candidates.values()) {
+            if (!pathMatchesPrefix(candidate.path, pathPrefix)) {
+                continue;
+            }
             if (isSuppressedPath(candidate.path)) {
                 continue;
             }
@@ -2864,7 +3221,7 @@ async function contextBundleImpl(context, params) {
         if (!hasAnyMetadataFilters) {
             return;
         }
-        const metadataRows = await fetchMetadataOnlyCandidates(db, context.tableAvailability, repoId, metadataFilters, limit * 2);
+        const metadataRows = await fetchMetadataOnlyCandidates(db, context.tableAvailability, repoId, metadataFilters, limit * 2, pathPrefix);
         if (metadataRows.length === 0) {
             return;
         }
@@ -2891,9 +3248,11 @@ async function contextBundleImpl(context, params) {
         await addMetadataFallbackCandidates();
     }
     let materializedCandidates = await materializeCandidates();
+    traceSearch(`materialized candidates: ${materializedCandidates.length}`);
     if (materializedCandidates.length === 0 && hasAnyMetadataFilters) {
         await addMetadataFallbackCandidates();
         materializedCandidates = await materializeCandidates();
+        traceSearch(`materialized candidates after metadata fallback: ${materializedCandidates.length}`);
     }
     if (materializedCandidates.length === 0) {
         // Get warnings from WarningManager (includes breaking change notification if applicable)
@@ -3021,6 +3380,14 @@ async function contextBundleImpl(context, params) {
         }
         return b.score - a.score;
     });
+    if (TRACE_SEARCH) {
+        const sample = rankedCandidates.slice(0, 5).map((candidate) => ({
+            path: candidate.path,
+            score: Number(candidate.score.toFixed(3)),
+            reasons: Array.from(candidate.reasons).slice(0, 3),
+        }));
+        traceSearch(`ranked candidates=${rankedCandidates.length}`, sample);
+    }
     const prioritizedCandidates = prioritizeHintCandidates(rankedCandidates, resolvedPathHintTargets.map((target) => target.path), limit);
     if (prioritizedCandidates.length === 0) {
         const warnings = [...context.warningManager.responseWarnings];