kiri-mcp-server 0.10.0 → 0.12.0

package/dist/src/server/handlers.js

@@ -3,10 +3,14 @@ import path from "node:path";
 import { checkFTSSchemaExists } from "../indexer/schema.js";
 import { generateEmbedding, structuralSimilarity } from "../shared/embedding.js";
 import { encode as encodeGPT, tokenizeText } from "../shared/tokenizer.js";
-import { getRepoPathCandidates, normalizeRepoPath } from "../shared/utils/path.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";
+// Re-export extracted handlers for backward compatibility
+export { snippetsGet, } from "./handlers/snippets-get.js";
 // Configuration file patterns (v0.8.0+: consolidated to avoid duplication)
 // Comprehensive list covering multiple languages and tools
 const CONFIG_FILES = [
@@ -133,6 +137,83 @@ const CONFIG_PATTERNS = [
     ".github/workflows",
 ];
 const FTS_STATUS_CACHE_TTL_MS = 10_000;
+const METADATA_ALIAS_MAP = new Map([
+    ["tag", { key: "tags" }],
+    ["tags", { key: "tags" }],
+    ["category", { key: "category" }],
+    ["title", { key: "title" }],
+    ["service", { key: "service" }],
+]);
+const METADATA_KEY_PREFIXES = [
+    { prefix: "meta." },
+    { prefix: "metadata.", strict: true },
+    { prefix: "docmeta.", strict: true },
+    { prefix: "frontmatter.", source: "front_matter" },
+    { prefix: "fm.", source: "front_matter" },
+    { prefix: "yaml.", source: "yaml" },
+    { prefix: "json.", source: "json" },
+];
+const METADATA_MATCH_WEIGHT = 0.15;
+const METADATA_FILTER_MATCH_WEIGHT = 0.1;
+const METADATA_HINT_BONUS = 0.25;
+const INBOUND_LINK_WEIGHT = 0.2;
+/**
+ * checkTableAvailability
+ *
+ * 起動時にテーブルの存在を確認し、TableAvailabilityオブジェクトを生成する。
+ * これにより、グローバルミュータブル変数による競合状態を回避する。
+ *
+ * NOTE: スキーマ変更（テーブル追加）後はサーバーの再起動が必要です。
+ *
+ * @param db - DuckDBClient インスタンス
+ * @returns TableAvailability オブジェクト
+ * @throws データベース接続エラー等、テーブル不在以外のエラーが発生した場合
+ */
+export async function checkTableAvailability(db) {
+    const ALLOWED_TABLES = [
+        "document_metadata_kv",
+        "markdown_link",
+        "hint_expansion",
+        "hint_dictionary",
+    ];
+    const checkTable = async (tableName) => {
+        if (!ALLOWED_TABLES.includes(tableName)) {
+            throw new Error(`Invalid table name: ${tableName}`);
+        }
+        try {
+            await db.all(`SELECT 1 FROM ${tableName} LIMIT 0`);
+            return true;
+        }
+        catch (error) {
+            // テーブル不在エラーのみキャッチ
+            if (isTableMissingError(error, tableName)) {
+                return false;
+            }
+            // その他のエラー（接続エラー等）は再スロー
+            throw new Error(`Failed to check table availability for ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
+    const result = {
+        hasMetadataTables: await checkTable("document_metadata_kv"),
+        hasLinkTable: await checkTable("markdown_link"),
+        hasHintLog: await checkTable("hint_expansion"),
+        hasHintDictionary: await checkTable("hint_dictionary"),
+    };
+    // 起動時警告: テーブルが存在しない場合に通知
+    if (!result.hasMetadataTables) {
+        console.warn("document_metadata_kv table is missing. Metadata filters and boosts disabled until database is upgraded.");
+    }
+    if (!result.hasLinkTable) {
+        console.warn("markdown_link table is missing. Inbound link boosting disabled until database is upgraded.");
+    }
+    if (!result.hasHintLog) {
+        console.warn("hint_expansion table is missing. Hint logging disabled. Enable the latest schema and rerun the indexer to capture hint logs.");
+    }
+    if (!result.hasHintDictionary) {
+        console.warn("hint_dictionary table is missing. Dictionary hints disabled. Run scripts/diag/build-hint-dictionary.ts after upgrading the schema.");
+    }
+    return result;
+}
 async function hasDirtyRepos(db) {
     const statusCheck = await db.all(`SELECT COUNT(*) as count FROM repo
        WHERE fts_dirty = true OR fts_status IN ('dirty', 'rebuilding')`);
@@ -217,44 +298,242 @@ function isConfigFile(path, fileName) {
         fileName.startsWith(".env") ||
         isInConfigDirectory);
 }
+function normalizeArtifactHints(hints) {
+    if (!Array.isArray(hints)) {
+        return [];
+    }
+    const normalized = [];
+    const seen = new Set();
+    for (const rawHint of hints) {
+        if (typeof rawHint !== "string") {
+            continue;
+        }
+        const trimmed = rawHint.trim();
+        if (!trimmed || seen.has(trimmed)) {
+            continue;
+        }
+        normalized.push(trimmed);
+        seen.add(trimmed);
+        if (normalized.length >= MAX_ARTIFACT_HINTS) {
+            break;
+        }
+    }
+    return normalized;
+}
+function bucketArtifactHints(hints) {
+    const buckets = {
+        pathHints: [],
+        substringHints: [],
+    };
+    for (const hint of hints) {
+        if (hint.includes("/") && SAFE_PATH_PATTERN.test(hint)) {
+            buckets.pathHints.push(hint);
+            continue;
+        }
+        const normalized = hint.trim().toLowerCase();
+        if (normalized.length >= 3) {
+            buckets.substringHints.push(normalized);
+        }
+    }
+    return buckets;
+}
+function isMissingTableError(error, table) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return /Table with name/i.test(error.message) && error.message.includes(table);
+}
+async function logHintExpansionEntry(db, tableAvailability, entry) {
+    if (!HINT_LOG_ENABLED) {
+        return;
+    }
+    if (!tableAvailability.hasHintLog) {
+        return;
+    }
+    try {
+        await db.run(`
+        INSERT INTO hint_expansion (repo_id, hint_value, expansion_kind, target_path, payload)
+        VALUES (?, ?, ?, ?, ?)
+      `, [
+            entry.repoId,
+            entry.hintValue,
+            entry.kind,
+            entry.targetPath ?? null,
+            entry.payload ? JSON.stringify(entry.payload) : null,
+        ]);
+    }
+    catch (error) {
+        if (isMissingTableError(error, "hint_expansion")) {
+            console.warn("hint_expansion table is missing in the active database. Enable the latest schema and rerun the indexer to capture hint logs.");
+            return;
+        }
+        throw error;
+    }
+}
+async function fetchDictionaryPathHints(db, tableAvailability, repoId, hints, perHintLimit) {
+    if (!HINT_DICTIONARY_ENABLED || perHintLimit <= 0 || hints.length === 0) {
+        return [];
+    }
+    if (!tableAvailability.hasHintDictionary) {
+        return [];
+    }
+    const uniqueHints = Array.from(new Set(hints));
+    const targets = [];
+    for (const hint of uniqueHints) {
+        let rows = [];
+        try {
+            rows = await db.all(`
+          SELECT target_path
+          FROM hint_dictionary
+          WHERE repo_id = ?
+            AND hint_value = ?
+          ORDER BY freq DESC, target_path
+          LIMIT ?
+        `, [repoId, hint, perHintLimit]);
+        }
+        catch (error) {
+            if (isMissingTableError(error, "hint_dictionary")) {
+                console.warn("hint_dictionary table is missing in the active database. Run scripts/diag/build-hint-dictionary.ts after upgrading the schema.");
+                return [];
+            }
+            throw error;
+        }
+        for (const row of rows) {
+            if (!row.target_path || !SAFE_PATH_PATTERN.test(row.target_path)) {
+                continue;
+            }
+            targets.push({ path: row.target_path, sourceHint: hint, origin: "dictionary" });
+        }
+    }
+    return targets;
+}
+function createHintSeedMeta(targets) {
+    const meta = new Map();
+    const deduped = [];
+    for (const target of targets) {
+        if (meta.has(target.path)) {
+            continue;
+        }
+        meta.set(target.path, { sourceHint: target.sourceHint, origin: target.origin });
+        deduped.push(target);
+    }
+    return { list: deduped, meta };
+}
+function getHintSeedMeta(seedMeta, path) {
+    return seedMeta?.get(path);
+}
+function computeHintPriorityBoost(weights) {
+    const textComponent = weights.textMatch * HINT_PRIORITY_TEXT_MULTIPLIER;
+    const pathComponent = weights.pathMatch * HINT_PRIORITY_PATH_MULTIPLIER;
+    const aggregate = textComponent + pathComponent + weights.editingPath + weights.dependency;
+    return Math.max(HINT_PRIORITY_BASE_BONUS, aggregate);
+}
+function createHintExpansionConfig(weights) {
+    return {
+        dirLimit: Math.max(0, HINT_DIR_LIMIT),
+        dirMaxFiles: Math.max(1, HINT_DIR_MAX_FILES),
+        depOutLimit: Math.max(0, HINT_DEP_OUT_LIMIT),
+        depInLimit: Math.max(0, HINT_DEP_IN_LIMIT),
+        semLimit: Math.max(0, HINT_SEM_LIMIT),
+        semDirCandidateLimit: Math.max(1, HINT_SEM_DIR_CANDIDATE_LIMIT),
+        semThreshold: Number.isFinite(HINT_SEM_THRESHOLD) ? HINT_SEM_THRESHOLD : 0.65,
+        perHintLimit: Math.max(0, HINT_PER_HINT_LIMIT),
+        dbQueryBudget: Math.max(0, HINT_DB_QUERY_BUDGET),
+        dirBoost: computeHintPriorityBoost(weights) * 0.35,
+        depBoost: weights.dependency * 0.8,
+        substringLimit: Math.max(0, HINT_SUBSTRING_LIMIT),
+        substringBoost: Math.max(0, HINT_SUBSTRING_BOOST),
+    };
+}
 const DEFAULT_SEARCH_LIMIT = 50;
-const DEFAULT_SNIPPET_WINDOW = 150;
 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 FALLBACK_SNIPPET_WINDOW = 40; // Reduced from 120 to optimize token usage
+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 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;
+const HINT_DEP_IN_LIMIT = serverConfig.hints.dependency.inLimit;
+const HINT_SEM_LIMIT = serverConfig.hints.semantic.limit;
+const HINT_SEM_DIR_CANDIDATE_LIMIT = serverConfig.hints.semantic.dirCandidateLimit;
+const HINT_SEM_THRESHOLD = serverConfig.hints.semantic.threshold;
+const SUPPRESSED_PATH_PREFIXES = [".github/", ".git/", "ThirdPartyNotices", "node_modules/"];
+const SUPPRESSED_FILE_NAMES = ["thirdpartynotices.txt", "thirdpartynotices.md", "cgmanifest.json"];
+function isSuppressedPath(path) {
+    if (!SUPPRESS_NON_CODE_ENABLED) {
+        return false;
+    }
+    const normalized = path.startsWith("./") ? path.replace(/^\.\/+/u, "") : path;
+    const lower = normalized.toLowerCase();
+    if (SUPPRESSED_FILE_NAMES.some((name) => lower.endsWith(name))) {
+        return true;
+    }
+    const lowerPrefixMatches = SUPPRESSED_PATH_PREFIXES.map((prefix) => prefix.toLowerCase());
+    return lowerPrefixMatches.some((prefix) => lower.includes(prefix));
+}
+const HINT_PER_HINT_LIMIT = serverConfig.hints.perHintLimit;
+const HINT_DB_QUERY_BUDGET = serverConfig.hints.dbQueryLimit;
+const HINT_SUBSTRING_LIMIT = serverConfig.hints.substring.limit;
+const HINT_SUBSTRING_BOOST = serverConfig.hints.substring.boost;
+const HINT_LOG_ENABLED = process.env.KIRI_HINT_LOG === "1";
+const HINT_DICTIONARY_ENABLED = process.env.KIRI_HINT_DICTIONARY !== "0";
+const HINT_DICTIONARY_LIMIT = Math.max(0, Number.parseInt(process.env.KIRI_HINT_DICTIONARY_LIMIT ?? "2", 10));
 // Issue #68: Path/Large File Penalty configuration (環境変数で上書き可能)
-const PATH_MISS_DELTA = parseFloat(process.env.KIRI_PATH_MISS_DELTA || "-0.5");
-const LARGE_FILE_DELTA = parseFloat(process.env.KIRI_LARGE_FILE_DELTA || "-0.8");
+const PATH_MISS_DELTA = serverConfig.penalties.pathMissDelta;
+const LARGE_FILE_DELTA = serverConfig.penalties.largeFileDelta;
 const MAX_WHY_TAGS = 10;
 // 項目3: whyタグの優先度マップ（低い数値ほど高優先度）
 // All actual tag prefixes used in the codebase
 const WHY_TAG_PRIORITY = {
-    artifact: 1, // User-provided hints (editing_path, failing_tests)
+    artifact: 1, // User-provided hints (editing_path, failing_tests, hints)
+    dictionary: 1, // Dictionary-provided hints
     phrase: 2, // Multi-word literal matches (strongest signal)
     text: 3, // Single keyword matches
-    "path-phrase": 4, // Path contains multi-word phrase
-    structural: 5, // Semantic similarity
-    "path-segment": 6, // Path component matches
-    "path-keyword": 7, // Path keyword match
-    dep: 8, // Dependency relationship
-    near: 9, // Proximity to editing file
-    boost: 10, // File type boost
-    recent: 11, // Recently changed
-    symbol: 12, // Symbol match
-    penalty: 13, // Penalty explanations (keep for transparency)
-    keyword: 14, // Generic keyword (deprecated, kept for compatibility)
+    metadata: 4, // Front matter / metadata filters & boosts
+    substring: 4, // Substring hint expansion
+    "path-phrase": 5, // Path contains multi-word phrase
+    structural: 6, // Semantic similarity
+    "path-segment": 7, // Path component matches
+    "path-keyword": 8, // Path keyword match
+    dep: 9, // Dependency relationship
+    near: 10, // Proximity to editing file
+    boost: 11, // File type boost
+    recent: 12, // Recently changed
+    symbol: 13, // Symbol match
+    penalty: 14, // Penalty explanations (keep for transparency)
+    keyword: 15, // Generic keyword (deprecated, kept for compatibility)
 };
 // Reserve at least one slot for important structural tags
 const RESERVED_WHY_SLOTS = {
     dep: 1, // Dependency relationships are critical
     symbol: 1, // Symbol boundaries help understand context
     near: 1, // Proximity explains file selection
+    metadata: 1, // Preserve metadata reasons when filters/boosts are active
 };
 function parseOutputOptions(params) {
     return {
@@ -277,6 +556,9 @@ function selectWhyTags(reasons) {
         reasons = new Set(Array.from(reasons).slice(0, 1000));
     }
     const selected = new Set();
+    if (reasons.has("boost:links")) {
+        selected.add("boost:links");
+    }
     const byCategory = new Map();
     for (const reason of reasons) {
         const prefix = reason.split(":")[0] ?? "";
@@ -342,6 +624,45 @@ const STOP_WORDS = new Set([
     "need",
     "goal",
 ]);
+function prioritizeHintCandidates(rankedCandidates, hintPaths, limit) {
+    if (rankedCandidates.length === 0) {
+        return [];
+    }
+    const sanitizedLimit = Math.max(1, Math.min(limit, rankedCandidates.length));
+    const candidateByPath = new Map();
+    for (const candidate of rankedCandidates) {
+        if (!candidateByPath.has(candidate.path)) {
+            candidateByPath.set(candidate.path, candidate);
+        }
+    }
+    const final = [];
+    const seen = new Set();
+    for (const hintPath of hintPaths) {
+        if (final.length >= sanitizedLimit) {
+            break;
+        }
+        const candidate = candidateByPath.get(hintPath);
+        if (!candidate || seen.has(candidate.path)) {
+            continue;
+        }
+        final.push(candidate);
+        seen.add(candidate.path);
+    }
+    if (final.length >= sanitizedLimit) {
+        return final;
+    }
+    for (const candidate of rankedCandidates) {
+        if (final.length >= sanitizedLimit) {
+            break;
+        }
+        if (seen.has(candidate.path)) {
+            continue;
+        }
+        final.push(candidate);
+        seen.add(candidate.path);
+    }
+    return final;
+}
 function normalizeLimit(limit) {
     if (!limit || Number.isNaN(limit)) {
         return DEFAULT_SEARCH_LIMIT;
@@ -502,8 +823,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) {
@@ -520,14 +863,361 @@ 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;
 }
+async function expandHintCandidatesForHints(params) {
+    const { hintPaths, config } = params;
+    if (hintPaths.length === 0 || config.perHintLimit <= 0 || config.dbQueryBudget <= 0) {
+        return;
+    }
+    const state = { remainingDbQueries: config.dbQueryBudget };
+    for (const hintPath of hintPaths) {
+        if (state.remainingDbQueries <= 0) {
+            break;
+        }
+        await expandSingleHintNeighborhood({ ...params, hintPath, state });
+    }
+}
+async function expandSingleHintNeighborhood(args) {
+    const { config } = args;
+    let remaining = config.perHintLimit;
+    if (remaining <= 0) {
+        return;
+    }
+    if (config.dirLimit > 0) {
+        const added = await addHintDirectoryNeighbors(args, Math.min(config.dirLimit, remaining));
+        remaining -= added;
+        if (remaining <= 0) {
+            return;
+        }
+    }
+    if (config.depOutLimit > 0 || config.depInLimit > 0) {
+        const added = await addHintDependencyNeighbors(args, remaining);
+        remaining -= added;
+        if (remaining <= 0) {
+            return;
+        }
+    }
+    if (config.semLimit > 0) {
+        await addHintSemanticNeighbors(args, Math.min(config.semLimit, remaining));
+    }
+}
+function useHintDbBudget(state, cost = 1) {
+    if (state.remainingDbQueries < cost) {
+        return false;
+    }
+    state.remainingDbQueries -= cost;
+    return true;
+}
+function applyHintReasonBoost(candidate, reason, scoreDelta, lang, ext) {
+    if (scoreDelta <= 0 || candidate.reasons.has(reason)) {
+        return false;
+    }
+    candidate.score += scoreDelta;
+    candidate.reasons.add(reason);
+    candidate.pathMatchHits = Math.max(candidate.pathMatchHits, 2);
+    candidate.matchLine ??= 1;
+    if (lang && !candidate.lang) {
+        candidate.lang = lang;
+    }
+    if (ext && !candidate.ext) {
+        candidate.ext = ext;
+    }
+    return true;
+}
+async function applyPathHintPromotions(args) {
+    const { hintTargets } = args;
+    if (hintTargets.length === 0) {
+        return;
+    }
+    const hintBoost = computeHintPriorityBoost(args.weights);
+    for (const target of hintTargets) {
+        const candidate = ensureCandidate(args.candidates, target.path);
+        const reasonPrefix = target.origin === "dictionary" ? "dictionary:hint" : "artifact:hint";
+        candidate.score += hintBoost;
+        candidate.reasons.add(`${reasonPrefix}:${target.path}`);
+        candidate.pathMatchHits = Math.max(candidate.pathMatchHits, 3);
+        candidate.matchLine ??= 1;
+        await logHintExpansionEntry(args.db, args.tableAvailability, {
+            repoId: args.repoId,
+            hintValue: target.sourceHint,
+            kind: target.origin === "dictionary" ? "dictionary" : "path",
+            targetPath: target.path,
+            payload: {
+                origin: target.origin,
+                source_hint: target.sourceHint,
+            },
+        });
+    }
+    await expandHintCandidatesForHints({
+        db: args.db,
+        tableAvailability: args.tableAvailability,
+        repoId: args.repoId,
+        hintPaths: hintTargets.map((target) => target.path),
+        candidates: args.candidates,
+        fileCache: args.fileCache,
+        weights: args.weights,
+        config: createHintExpansionConfig(args.weights),
+        hintSeedMeta: args.hintSeedMeta,
+    });
+}
+async function addHintSubstringMatches(db, tableAvailability, repoId, hints, candidates, limitPerHint, boost) {
+    if (limitPerHint <= 0 || boost <= 0) {
+        return;
+    }
+    for (const hint of hints) {
+        if (!SAFE_PATH_PATTERN.test(hint.replace(/[^a-zA-Z0-9_.-]/g, ""))) {
+            continue;
+        }
+        const rows = await db.all(`
+        SELECT path
+        FROM file
+        WHERE repo_id = ?
+          AND is_binary = FALSE
+          AND LOWER(path) LIKE '%' || ? || '%'
+        ORDER BY path
+        LIMIT ?
+      `, [repoId, hint, limitPerHint]);
+        for (const row of rows) {
+            const candidate = ensureCandidate(candidates, row.path);
+            const reason = `substring:hint:${hint}`;
+            if (applyHintReasonBoost(candidate, reason, boost)) {
+                await logHintExpansionEntry(db, tableAvailability, {
+                    repoId,
+                    hintValue: hint,
+                    kind: "substring",
+                    targetPath: row.path,
+                });
+            }
+        }
+    }
+}
+async function addHintDirectoryNeighbors(args, limit) {
+    if (limit <= 0) {
+        return 0;
+    }
+    const dir = path.posix.dirname(args.hintPath);
+    if (!dir || dir === "." || dir === "/") {
+        return 0;
+    }
+    if (!useHintDbBudget(args.state)) {
+        return 0;
+    }
+    const rows = await args.db.all(`
+      SELECT path, lang, ext
+      FROM file
+      WHERE repo_id = ?
+        AND is_binary = FALSE
+        AND path LIKE ?
+      ORDER BY path
+      LIMIT ?
+    `, [args.repoId, `${dir}/%`, args.config.dirMaxFiles + 1]);
+    if (rows.length === 0 || rows.length > args.config.dirMaxFiles) {
+        return 0;
+    }
+    rows.sort((a, b) => hintNeighborRank(a.path) - hintNeighborRank(b.path));
+    let added = 0;
+    for (const row of rows) {
+        if (row.path === args.hintPath) {
+            continue;
+        }
+        if (!SAFE_PATH_PATTERN.test(row.path)) {
+            continue;
+        }
+        const candidate = ensureCandidate(args.candidates, row.path);
+        const reason = `artifact:hint_dir:${args.hintPath}:${row.path}`;
+        if (applyHintReasonBoost(candidate, reason, args.config.dirBoost, row.lang, row.ext)) {
+            added += 1;
+            const seedMeta = getHintSeedMeta(args.hintSeedMeta, args.hintPath);
+            await logHintExpansionEntry(args.db, args.tableAvailability, {
+                repoId: args.repoId,
+                hintValue: seedMeta?.sourceHint ?? args.hintPath,
+                kind: "directory",
+                targetPath: row.path,
+                payload: {
+                    origin: seedMeta?.origin ?? "artifact",
+                },
+            });
+            if (added >= limit) {
+                break;
+            }
+        }
+    }
+    return added;
+}
+async function addHintDependencyNeighbors(args, perHintRemaining) {
+    if (perHintRemaining <= 0) {
+        return 0;
+    }
+    let added = 0;
+    if (args.config.depOutLimit > 0) {
+        const outLimit = Math.min(args.config.depOutLimit, perHintRemaining - added);
+        if (outLimit > 0) {
+            added += await addHintDependencyDirection(args, outLimit, "out");
+        }
+    }
+    if (perHintRemaining - added <= 0) {
+        return added;
+    }
+    if (args.config.depInLimit > 0) {
+        const inLimit = Math.min(args.config.depInLimit, perHintRemaining - added);
+        if (inLimit > 0) {
+            added += await addHintDependencyDirection(args, inLimit, "in");
+        }
+    }
+    return added;
+}
+async function addHintDependencyDirection(args, limit, direction) {
+    if (limit <= 0) {
+        return 0;
+    }
+    if (!useHintDbBudget(args.state)) {
+        return 0;
+    }
+    const fetchLimit = Math.min(limit * 4, 25);
+    if (direction === "out") {
+        const rows = await args.db.all(`
+        SELECT dst
+        FROM dependency
+        WHERE repo_id = ?
+          AND src_path = ?
+          AND dst_kind = 'path'
+        LIMIT ?
+      `, [args.repoId, args.hintPath, fetchLimit]);
+        return await applyDependencyRows(args, rows.map((row) => row.dst), limit, direction);
+    }
+    const rows = await args.db.all(`
+      SELECT src_path
+      FROM dependency
+      WHERE repo_id = ?
+        AND dst = ?
+        AND dst_kind = 'path'
+      LIMIT ?
+    `, [args.repoId, args.hintPath, fetchLimit]);
+    return await applyDependencyRows(args, rows.map((row) => row.src_path), limit, direction);
+}
+async function applyDependencyRows(args, paths, limit, direction) {
+    if (paths.length === 0) {
+        return 0;
+    }
+    const uniquePaths = Array.from(new Set(paths)).filter((p) => p && SAFE_PATH_PATTERN.test(p));
+    uniquePaths.sort((a, b) => hintNeighborRank(a) - hintNeighborRank(b));
+    let added = 0;
+    for (const dependencyPath of uniquePaths) {
+        if (dependencyPath === args.hintPath) {
+            continue;
+        }
+        const candidate = ensureCandidate(args.candidates, dependencyPath);
+        const reason = `artifact:hint_dep_${direction}:${args.hintPath}:${dependencyPath}`;
+        if (applyHintReasonBoost(candidate, reason, args.config.depBoost)) {
+            added += 1;
+            const seedMeta = getHintSeedMeta(args.hintSeedMeta, args.hintPath);
+            await logHintExpansionEntry(args.db, args.tableAvailability, {
+                repoId: args.repoId,
+                hintValue: seedMeta?.sourceHint ?? args.hintPath,
+                kind: "dependency",
+                targetPath: dependencyPath,
+                payload: {
+                    origin: seedMeta?.origin ?? "artifact",
+                    direction,
+                },
+            });
+            if (added >= limit) {
+                break;
+            }
+        }
+    }
+    return added;
+}
+async function addHintSemanticNeighbors(args, limit) {
+    if (limit <= 0) {
+        return 0;
+    }
+    const dir = path.posix.dirname(args.hintPath);
+    if (!dir || dir === "." || dir === "/") {
+        return 0;
+    }
+    if (!useHintDbBudget(args.state)) {
+        return 0;
+    }
+    const rows = await args.db.all(`
+      SELECT path
+      FROM file
+      WHERE repo_id = ?
+        AND is_binary = FALSE
+        AND path LIKE ?
+      ORDER BY path
+      LIMIT ?
+    `, [args.repoId, `${dir}/%`, args.config.semDirCandidateLimit]);
+    const candidatePaths = rows.map((row) => row.path).filter((p) => p !== args.hintPath);
+    if (candidatePaths.length === 0) {
+        return 0;
+    }
+    if (!useHintDbBudget(args.state)) {
+        return 0;
+    }
+    const embeddingMap = await fetchEmbeddingMap(args.db, args.repoId, [
+        args.hintPath,
+        ...candidatePaths,
+    ]);
+    const hintEmbedding = embeddingMap.get(args.hintPath);
+    if (!hintEmbedding) {
+        return 0;
+    }
+    let added = 0;
+    for (const candidatePath of candidatePaths) {
+        if (!SAFE_PATH_PATTERN.test(candidatePath)) {
+            continue;
+        }
+        const embedding = embeddingMap.get(candidatePath);
+        if (!embedding) {
+            continue;
+        }
+        const similarity = structuralSimilarity(hintEmbedding, embedding);
+        if (!Number.isFinite(similarity) || similarity < args.config.semThreshold) {
+            continue;
+        }
+        const candidate = ensureCandidate(args.candidates, candidatePath);
+        const reason = `artifact:hint_sem:${args.hintPath}:${candidatePath}`;
+        if (applyHintReasonBoost(candidate, reason, args.weights.structural * similarity)) {
+            added += 1;
+            if (added >= limit) {
+                break;
+            }
+        }
+    }
+    return added;
+}
+function hintNeighborRank(filePath) {
+    if (filePath.startsWith("src/") || filePath.startsWith("external/assay-kit/src/")) {
+        return 0;
+    }
+    if (isTestLikePath(filePath)) {
+        return 2;
+    }
+    if (filePath.startsWith("docs/")) {
+        return 3;
+    }
+    return 1;
+}
+function isTestLikePath(filePath) {
+    return (/(^|\/)(tests?|__tests__|fixtures)\//.test(filePath) ||
+        filePath.endsWith(".spec.ts") ||
+        filePath.endsWith(".spec.tsx") ||
+        filePath.endsWith(".test.ts") ||
+        filePath.endsWith(".test.tsx"));
+}
 function parseEmbedding(vectorJson, vectorDims) {
-    if (!vectorJson || !vectorDims || vectorDims <= 0) {
+    const dims = vectorDims === null ? null : typeof vectorDims === "bigint" ? Number(vectorDims) : vectorDims;
+    if (!vectorJson || !dims || dims <= 0) {
         return null;
     }
     try {
@@ -536,7 +1226,7 @@ function parseEmbedding(vectorJson, vectorDims) {
             return null;
         }
         const values = [];
-        for (let i = 0; i < parsed.length && i < vectorDims; i += 1) {
+        for (let i = 0; i < parsed.length && i < dims; i += 1) {
             const raw = parsed[i];
             const num = typeof raw === "number" ? raw : Number(raw);
             if (!Number.isFinite(num)) {
@@ -544,7 +1234,7 @@ function parseEmbedding(vectorJson, vectorDims) {
             }
             values.push(num);
         }
-        return values.length === vectorDims ? values : null;
+        return values.length === dims ? values : null;
     }
     catch {
         return null;
@@ -636,54 +1326,411 @@ function buildSnippetPreview(content, startLine, endLine) {
     if (snippet.length <= 240) {
         return snippet;
     }
-    return `${snippet.slice(0, 239)}…`;
+    return `${snippet.slice(0, 239)}…`;
+}
+/**
+ * トークン数を推定（コンテンツベース）
+ * 実際のGPTトークナイザーを使用して正確にカウント
+ *
+ * @param content - ファイル全体のコンテンツ
+ * @param startLine - 開始行（1-indexed）
+ * @param endLine - 終了行（1-indexed）
+ * @returns 推定トークン数
+ */
+function estimateTokensFromContent(content, startLine, endLine) {
+    const lines = content.split(/\r?\n/);
+    const startIndex = Math.max(0, startLine - 1);
+    const endIndex = Math.min(endLine, lines.length);
+    const selectedLines = lines.slice(startIndex, endIndex);
+    const text = selectedLines.join("\n");
+    try {
+        // 実際のGPTトークナイザーを使用
+        return encodeGPT(text).length;
+    }
+    catch (error) {
+        // フォールバック: 平均的な英語テキストで4文字 ≈ 1トークン
+        console.warn("Token encoding failed, using character-based fallback", error);
+        return Math.max(1, Math.ceil(text.length / 4));
+    }
+}
+/**
+ * 複数単語クエリを単語分割してOR検索条件を構築
+ * @param query - 検索クエリ文字列
+ * @returns 単語配列（2文字以下を除外）
+ */
+function splitQueryWords(query) {
+    // 空白、スラッシュ、ハイフン、アンダースコアで分割
+    const words = query.split(/[\s/\-_]+/).filter((w) => w.length > 2);
+    return words.length > 0 ? words : [query]; // 全て除外された場合は元のクエリを使用
+}
+function normalizeMetadataFilterKey(rawKey) {
+    if (!rawKey) {
+        return null;
+    }
+    const normalized = rawKey.toLowerCase();
+    const alias = METADATA_ALIAS_MAP.get(normalized);
+    if (alias) {
+        return { ...alias };
+    }
+    for (const entry of METADATA_KEY_PREFIXES) {
+        if (normalized.startsWith(entry.prefix)) {
+            const remainder = normalized.slice(entry.prefix.length);
+            if (!remainder) {
+                return null;
+            }
+            return {
+                key: remainder,
+                source: entry.source,
+                ...(entry.strict !== undefined && { strict: entry.strict }),
+            };
+        }
+    }
+    return null;
+}
+function normalizeFilterValues(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : [];
+    }
+    if (Array.isArray(value)) {
+        const values = [];
+        for (const item of value) {
+            if (typeof item === "string") {
+                const trimmed = item.trim();
+                if (trimmed) {
+                    values.push(trimmed);
+                }
+            }
+        }
+        return values;
+    }
+    return [];
+}
+function normalizeMetadataFiltersParam(input) {
+    if (!input || typeof input !== "object") {
+        return [];
+    }
+    const filters = [];
+    for (const [rawKey, rawValue] of Object.entries(input)) {
+        const normalizedKey = normalizeMetadataFilterKey(rawKey);
+        if (!normalizedKey) {
+            continue;
+        }
+        const values = normalizeFilterValues(rawValue);
+        if (values.length === 0) {
+            continue;
+        }
+        const filter = {
+            key: normalizedKey.key,
+            values,
+            source: normalizedKey.source,
+        };
+        if (normalizedKey.strict !== undefined) {
+            filter.strict = normalizedKey.strict;
+        }
+        filters.push(filter);
+    }
+    return filters;
+}
+function mergeMetadataFilters(filters) {
+    const merged = new Map();
+    for (const filter of filters) {
+        if (filter.values.length === 0)
+            continue;
+        const mapKey = `${filter.source ?? "*"}::${filter.key}::${filter.strict ? "strict" : "hint"}`;
+        const existing = merged.get(mapKey);
+        if (existing) {
+            const existingSet = new Set(existing.values.map((val) => val.toLowerCase()));
+            for (const value of filter.values) {
+                if (!existingSet.has(value.toLowerCase())) {
+                    existing.values.push(value);
+                    existingSet.add(value.toLowerCase());
+                }
+            }
+        }
+        else {
+            const entry = {
+                key: filter.key,
+                source: filter.source,
+                values: [...filter.values],
+            };
+            if (filter.strict !== undefined) {
+                entry.strict = filter.strict;
+            }
+            merged.set(mapKey, entry);
+        }
+    }
+    return Array.from(merged.values());
+}
+function parseInlineMetadataFilters(query) {
+    if (!query) {
+        return { cleanedQuery: "", filters: [] };
+    }
+    const matches = [];
+    const pattern = /(\b[\w.]+):("[^"]+"|'[^']+'|[^\s]+)/g;
+    let match;
+    while ((match = pattern.exec(query)) !== null) {
+        const normalizedKey = normalizeMetadataFilterKey(match[1] ?? "");
+        if (!normalizedKey) {
+            continue;
+        }
+        let rawValue = match[2] ?? "";
+        if ((rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+            (rawValue.startsWith("'") && rawValue.endsWith("'"))) {
+            rawValue = rawValue.slice(1, -1);
+        }
+        const value = rawValue.trim();
+        if (!value) {
+            continue;
+        }
+        const filter = {
+            key: normalizedKey.key,
+            source: normalizedKey.source,
+            values: [value],
+        };
+        if (normalizedKey.strict !== undefined) {
+            filter.strict = normalizedKey.strict;
+        }
+        matches.push({
+            start: match.index,
+            end: pattern.lastIndex,
+            filter,
+        });
+    }
+    if (matches.length === 0) {
+        return { cleanedQuery: query.trim(), filters: [] };
+    }
+    let cleaned = "";
+    let lastIndex = 0;
+    for (const info of matches) {
+        cleaned += query.slice(lastIndex, info.start);
+        lastIndex = info.end;
+    }
+    cleaned += query.slice(lastIndex);
+    const normalizedQuery = cleaned.replace(/\s{2,}/g, " ").trim();
+    return {
+        cleanedQuery: normalizedQuery,
+        filters: mergeMetadataFilters(matches.map((m) => m.filter)),
+    };
+}
+function buildMetadataFilterConditions(filters, alias = "f") {
+    // SQL Injection対策: aliasをリテラル型で制限し、念のため検証
+    if (!["f", "mk"].includes(alias)) {
+        throw new Error(`Invalid SQL alias: ${alias}`);
+    }
+    const clauses = [];
+    for (const filter of filters) {
+        if (!filter.key || filter.values.length === 0) {
+            continue;
+        }
+        const likeClauses = filter.values.map(() => "mk.value ILIKE ?").join(" OR ");
+        const whereParts = [`mk.repo_id = ${alias}.repo_id`, `mk.path = ${alias}.path`];
+        const params = [];
+        if (filter.source) {
+            whereParts.push("mk.source = ?");
+            params.push(filter.source);
+        }
+        whereParts.push("mk.key = ?");
+        params.push(filter.key);
+        whereParts.push(`(${likeClauses})`);
+        params.push(...filter.values.map((value) => `%${value}%`));
+        const sql = `EXISTS (SELECT 1 FROM document_metadata_kv mk WHERE ${whereParts.join(" AND ")})`;
+        clauses.push({ sql, params });
+    }
+    return clauses;
+}
+function isTableMissingError(error, table) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return error.message.includes(`Table with name ${table}`) || error.message.includes(table);
+}
+async function safeMetadataQuery(db, tableAvailability, sql, params) {
+    if (!tableAvailability.hasMetadataTables) {
+        return [];
+    }
+    try {
+        return await db.all(sql, params);
+    }
+    catch (error) {
+        if (isTableMissingError(error, "document_metadata_kv")) {
+            console.warn("Metadata tables not found; disabling metadata filters and boosts until database is upgraded.");
+            return [];
+        }
+        throw error;
+    }
+}
+async function safeLinkQuery(db, tableAvailability, sql, params) {
+    if (!tableAvailability.hasLinkTable) {
+        return [];
+    }
+    try {
+        return await db.all(sql, params);
+    }
+    catch (error) {
+        if (isTableMissingError(error, "markdown_link")) {
+            console.warn("Markdown link table not found; inbound link boosting disabled until database is upgraded.");
+            return [];
+        }
+        throw error;
+    }
+}
+async function fetchMetadataOnlyCandidates(db, tableAvailability, repoId, filters, limit) {
+    if (!tableAvailability.hasMetadataTables || filters.length === 0 || limit <= 0) {
+        return [];
+    }
+    const filterClauses = buildMetadataFilterConditions(filters);
+    const whereClauses = ["f.repo_id = ?"];
+    const params = [repoId];
+    for (const clause of filterClauses) {
+        whereClauses.push(clause.sql);
+        params.push(...clause.params);
+    }
+    const sql = `
+    SELECT f.path, f.lang, f.ext, b.content
+    FROM file f
+    JOIN blob b ON b.hash = f.blob_hash
+    WHERE ${whereClauses.join(" AND ")}
+    ORDER BY f.path
+    LIMIT ?
+  `;
+    params.push(limit);
+    try {
+        return await db.all(sql, params);
+    }
+    catch (error) {
+        if (isTableMissingError(error, "document_metadata_kv")) {
+            console.warn("Metadata tables not found; disabling metadata-only searches until database is upgraded.");
+            return [];
+        }
+        throw error;
+    }
+}
+async function fetchMetadataKeywordMatches(db, tableAvailability, repoId, keywords, filters, limit, excludePaths) {
+    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 (excludePaths.size > 0) {
+        const placeholders = Array.from(excludePaths)
+            .map(() => "?")
+            .join(", ");
+        whereClauses.push(`f.path NOT IN (${placeholders})`);
+        params.push(...excludePaths);
+    }
+    const filterClauses = buildMetadataFilterConditions(filters, "f");
+    for (const clause of filterClauses) {
+        whereClauses.push(clause.sql);
+        params.push(...clause.params);
+    }
+    params.push(limit);
+    const sql = `
+    SELECT f.path, f.lang, f.ext, b.content, COUNT(*) AS score
+    FROM document_metadata_kv mk
+    JOIN file f ON f.repo_id = mk.repo_id AND f.path = mk.path
+    JOIN blob b ON b.hash = f.blob_hash
+    WHERE ${whereClauses.join(" AND ")}
+    GROUP BY f.path, f.lang, f.ext, b.content
+    ORDER BY score DESC, f.path
+    LIMIT ?
+  `;
+    const rows = await safeMetadataQuery(db, tableAvailability, sql, params);
+    return rows.map((row) => ({ ...row, score: Number(row.score ?? 1) }));
+}
+async function loadMetadataForPaths(db, tableAvailability, repoId, paths) {
+    const result = new Map();
+    if (!tableAvailability.hasMetadataTables || paths.length === 0) {
+        return result;
+    }
+    const placeholders = paths.map(() => "?").join(", ");
+    const sql = `
+    SELECT path, key, value, source
+    FROM document_metadata_kv
+    WHERE repo_id = ? AND path IN (${placeholders})
+  `;
+    const rows = await safeMetadataQuery(db, tableAvailability, sql, [repoId, ...paths]);
+    for (const row of rows) {
+        if (!result.has(row.path)) {
+            result.set(row.path, []);
+        }
+        result.get(row.path).push({
+            key: row.key,
+            value: row.value,
+            source: row.source ?? undefined,
+        });
+    }
+    return result;
 }
-function prependLineNumbers(snippet, startLine) {
-    const lines = snippet.split(/\r?\n/);
-    if (lines.length === 0) {
-        return snippet;
+async function loadInboundLinkCounts(db, tableAvailability, repoId, paths) {
+    const counts = new Map();
+    if (!tableAvailability.hasLinkTable || paths.length === 0) {
+        return counts;
     }
-    // Calculate required width from the last line number (dynamic sizing)
-    const endLine = startLine + lines.length - 1;
-    const width = String(endLine).length;
-    return lines
-        .map((line, index) => `${String(startLine + index).padStart(width, " ")}→${line}`)
-        .join("\n");
+    const placeholders = paths.map(() => "?").join(", ");
+    const sql = `
+    SELECT resolved_path AS path, COUNT(*) AS inbound
+    FROM markdown_link
+    WHERE repo_id = ? AND resolved_path IS NOT NULL AND resolved_path IN (${placeholders})
+    GROUP BY resolved_path
+  `;
+    const rows = await safeLinkQuery(db, tableAvailability, sql, [repoId, ...paths]);
+    for (const row of rows) {
+        const inboundValue = typeof row.inbound === "bigint" ? Number(row.inbound) : Number(row.inbound ?? 0);
+        counts.set(row.path, inboundValue);
+    }
+    return counts;
 }
-/**
- * トークン数を推定（コンテンツベース）
- * 実際のGPTトークナイザーを使用して正確にカウント
- *
- * @param content - ファイル全体のコンテンツ
- * @param startLine - 開始行（1-indexed）
- * @param endLine - 終了行（1-indexed）
- * @returns 推定トークン数
- */
-function estimateTokensFromContent(content, startLine, endLine) {
-    const lines = content.split(/\r?\n/);
-    const startIndex = Math.max(0, startLine - 1);
-    const endIndex = Math.min(endLine, lines.length);
-    const selectedLines = lines.slice(startIndex, endIndex);
-    const text = selectedLines.join("\n");
-    try {
-        // 実際のGPTトークナイザーを使用
-        return encodeGPT(text).length;
+function computeMetadataBoost(entries, keywordSet, filterValueSet) {
+    if (!entries || entries.length === 0) {
+        return 0;
     }
-    catch (error) {
-        // フォールバック: 平均的な英語テキストで4文字 ≈ 1トークン
-        console.warn("Token encoding failed, using character-based fallback", error);
-        return Math.max(1, Math.ceil(text.length / 4));
+    let boost = 0;
+    for (const entry of entries) {
+        const valueLower = entry.value.toLowerCase();
+        for (const keyword of keywordSet) {
+            if (valueLower.includes(keyword)) {
+                boost += METADATA_MATCH_WEIGHT;
+                break;
+            }
+        }
+        if (filterValueSet.has(valueLower)) {
+            boost += METADATA_FILTER_MATCH_WEIGHT;
+        }
     }
+    return Math.min(boost, 1.5);
 }
-/**
- * 複数単語クエリを単語分割してOR検索条件を構築
- * @param query - 検索クエリ文字列
- * @returns 単語配列（2文字以下を除外）
- */
-function splitQueryWords(query) {
-    // 空白、スラッシュ、ハイフン、アンダースコアで分割
-    const words = query.split(/[\s/\-_]+/).filter((w) => w.length > 2);
-    return words.length > 0 ? words : [query]; // 全て除外された場合は元のクエリを使用
+function computeInboundLinkBoost(count) {
+    let numericCount = count;
+    if (typeof numericCount === "bigint") {
+        numericCount = Number(numericCount);
+    }
+    if (!numericCount || numericCount <= 0) {
+        return 0;
+    }
+    return Math.min(Math.log1p(numericCount) * INBOUND_LINK_WEIGHT, 1.0);
+}
+function candidateMatchesMetadataFilters(entries, filters) {
+    if (filters.length === 0) {
+        return true;
+    }
+    if (!entries || entries.length === 0) {
+        return false;
+    }
+    return filters.every((filter) => {
+        const expectedValues = filter.values.map((value) => value.toLowerCase());
+        return entries.some((entry) => {
+            if (entry.key !== filter.key) {
+                return false;
+            }
+            if (filter.source && entry.source !== filter.source) {
+                return false;
+            }
+            const lowerValue = entry.value.toLowerCase();
+            return expectedValues.some((value) => lowerValue.includes(value));
+        });
+    });
 }
 /**
  * パス固有のマルチプライヤーを取得（最長プレフィックスマッチ）
@@ -710,7 +1757,7 @@ function getPathMultiplier(filePath, profileConfig) {
  * @param weights - スコアリングウェイト設定（乗算的ペナルティに使用）
  * @returns ブースト適用後のスコア
  */
-function applyFileTypeBoost(path, baseScore, profileConfig, _weights) {
+function applyFileTypeBoost(path, baseScore, profileConfig, weights) {
     // Blacklisted directories that are almost always irrelevant for code context
     const blacklistedDirs = [
         ".cursor/",
@@ -727,7 +1774,8 @@ function applyFileTypeBoost(path, baseScore, profileConfig, _weights) {
             if (profileConfig.denylistOverrides.includes(dir)) {
                 continue;
             }
-            return -100; // Effectively remove it
+            // v1.0.0: Use multiplicative penalty instead of absolute -100
+            return baseScore * weights.blacklistPenaltyMultiplier;
         }
     }
     const fileName = path.split("/").pop() ?? "";
@@ -758,12 +1806,56 @@ function applyFileTypeBoost(path, baseScore, profileConfig, _weights) {
             multiplier *= implMultiplier;
         }
     }
-    // Test files: additive penalty (keep strong for files_search)
+    // Test files: multiplicative penalty (v1.0.0)
     if (path.startsWith("tests/") || path.startsWith("test/")) {
-        return baseScore * 0.2; // Strong penalty for tests
+        return baseScore * weights.testPenaltyMultiplier;
     }
     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のキーワード/フレーズがファイルパスに含まれる場合にスコアを加算
@@ -862,22 +1954,25 @@ function applyPathBasedScoring(candidate, lowerPath, weights, extractedTerms) {
     }
 }
 /**
- * 加算的ファイルペナルティを適用
- * ブラックリストディレクトリ、テストファイル、lockファイル、設定ファイル、マイグレーションファイルに強いペナルティ
- * @param profile - boost_profile設定（"docs"の場合はdocs/ディレクトリのブラックリストをスキップ）
- * @returns true if penalty was applied and processing should stop
+ * 乗算的ファイルペナルティを適用（v1.0.0+）
+ * ブラックリストディレクトリ、テストファイル、lockファイルに乗算ペナルティ
+ * v1.0.0: 絶対ペナルティ(-100)から乗算ペナルティ(×0.01など)に移行
+ * @param weights - スコアリングウェイト設定（乗算ペナルティ係数を含む）
+ * @param profile - boost_profile設定（denylistOverridesなど）
+ * @returns true if severe penalty was applied (caller should skip further boosts)
  */
-function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profileConfig) {
-    // Blacklisted directories - effectively remove
+function applyMultiplicativeFilePenalties(candidate, path, lowerPath, fileName, weights, profileConfig) {
+    // Returns true if a severe penalty was applied (should skip further boosts)
+    // Blacklisted directories - apply strong multiplicative penalty (99% reduction)
+    // v1.0.0: test/ and tests/ removed - handled by testPenaltyMultiplier instead
     const blacklistedDirs = [
         ".cursor/",
         ".devcontainer/",
         ".serena/",
         "__mocks__/",
         "docs/",
-        "test/",
-        "tests/",
         ".git/",
+        ".github/",
         "node_modules/",
         "db/migrate/",
         "db/migrations/",
@@ -897,19 +1992,26 @@ function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profil
             if (profileConfig.denylistOverrides.includes(dir)) {
                 continue; // Skip this blacklisted directory
             }
-            candidate.score = -100;
+            // v1.0.0: Use multiplicative penalty instead of absolute -100
+            candidate.scoreMultiplier *= weights.blacklistPenaltyMultiplier;
             candidate.reasons.add("penalty:blacklisted-dir");
-            return true;
+            return true; // Signal to skip further boosts - this is the strongest penalty
         }
     }
-    // Test files - strong penalty
+    if (isSuppressedPath(path)) {
+        // v1.0.0: Use multiplicative penalty instead of absolute -100
+        candidate.scoreMultiplier *= weights.blacklistPenaltyMultiplier;
+        candidate.reasons.add("penalty:suppressed");
+        return true; // Signal to skip further boosts
+    }
+    // Test files - strong multiplicative penalty (95% reduction)
     const testPatterns = [".spec.ts", ".spec.js", ".test.ts", ".test.js", ".spec.tsx", ".test.tsx"];
     if (testPatterns.some((pattern) => lowerPath.endsWith(pattern))) {
-        candidate.score -= 2.0;
+        candidate.scoreMultiplier *= weights.testPenaltyMultiplier;
         candidate.reasons.add("penalty:test-file");
-        return true;
+        return true; // Signal to skip further boosts
     }
-    // Lock files - very strong penalty
+    // Lock files - very strong multiplicative penalty (99% reduction)
     const lockFiles = [
         "package-lock.json",
         "pnpm-lock.yaml",
@@ -920,63 +2022,58 @@ function applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profil
         "poetry.lock",
     ];
     if (lockFiles.some((lockFile) => fileName === lockFile)) {
-        candidate.score -= 3.0;
+        candidate.scoreMultiplier *= weights.lockPenaltyMultiplier;
         candidate.reasons.add("penalty:lock-file");
-        return true;
-    }
-    // Configuration files - penalty handling depends on profile
-    const configPatterns = [
-        ".config.js",
-        ".config.ts",
-        ".config.mjs",
-        ".config.cjs",
-        "tsconfig.json",
-        "jsconfig.json",
-        "package.json",
-        ".eslintrc",
-        ".prettierrc",
-        "jest.config",
-        "vite.config",
-        "vitest.config",
-        "webpack.config",
-        "rollup.config",
-    ];
-    if (configPatterns.some((pattern) => lowerPath.endsWith(pattern) || fileName.startsWith(".env")) ||
-        fileName === "Dockerfile" ||
-        fileName === "docker-compose.yml" ||
-        fileName === "docker-compose.yaml") {
-        // ✅ Use explicit flag instead of magic number (0.3) to determine behavior
-        // This decouples profile detection from multiplier values
-        if (profileConfig.skipConfigAdditivePenalty) {
-            return false; // Continue to multiplicative penalty only
-        }
-        // For other profiles, apply strong additive penalty
-        candidate.score -= 1.5;
-        candidate.reasons.add("penalty:config-file");
-        return true;
+        return true; // Signal to skip further boosts
     }
-    // Migration files - strong penalty
-    if (lowerPath.includes("migrate") || lowerPath.includes("migration")) {
-        candidate.score -= 2.0;
-        candidate.reasons.add("penalty:migration-file");
-        return true;
-    }
-    return false; // No penalty applied, continue processing
+    // v1.0.0: No penalty applied, allow further boosts/penalties
+    return false;
 }
 /**
  * ファイルタイプ別の乗算的ペナルティ/ブーストを適用（v0.7.0+）
  * profile="docs": ドキュメントファイルをブースト
  * profile="default": ドキュメントファイルにペナルティ、実装ファイルをブースト
  */
-function applyFileTypeMultipliers(candidate, path, ext, profileConfig, _weights) {
+function applyFileTypeMultipliers(candidate, path, ext, profileConfig, weights) {
     const fileName = path.split("/").pop() ?? "";
-    // ✅ Step 1: Config files
+    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/") &&
+        (lowerPath.endsWith(".tmlanguage") ||
+            lowerPath.endsWith(".tmlanguage.json") ||
+            lowerPath.endsWith(".tmtheme") ||
+            lowerPath.endsWith(".plist"));
+    const isPerfData = lowerPath.includes(".perf.data") ||
+        lowerPath.includes(".perf-data") ||
+        lowerPath.includes("-perf-data");
+    const isLegalFile = fileName.toLowerCase().includes("thirdpartynotices") ||
+        fileName.toLowerCase() === "cgmanifest.json";
+    const isMigrationFile = lowerPath.includes("migrate") || lowerPath.includes("migration");
+    if (isSyntaxGrammar || isPerfData || isLegalFile || isMigrationFile) {
+        candidate.scoreMultiplier *= weights.configPenaltyMultiplier;
+        candidate.reasons.add("penalty:low-value-file");
+        return; // Don't apply impl boosts
+    }
+    // ✅ Step 2: Config files
     if (isConfigFile(path, fileName)) {
         candidate.scoreMultiplier *= profileConfig.fileTypeMultipliers.config;
         candidate.reasons.add("penalty:config-file");
         return; // Don't apply impl boosts to config files
     }
-    // ✅ Step 2: Documentation files
+    // ✅ Step 3: Documentation files
     const docExtensions = [".md", ".yaml", ".yml", ".mdc"];
     if (docExtensions.some((docExt) => path.endsWith(docExt))) {
         const docMultiplier = profileConfig.fileTypeMultipliers.doc;
@@ -989,7 +2086,7 @@ function applyFileTypeMultipliers(candidate, path, ext, profileConfig, _weights)
         }
         return; // Don't apply impl boosts to docs
     }
-    // ✅ Step 3: Implementation files with path-specific boosts
+    // ✅ Step 4: Implementation files with path-specific boosts
     const implMultiplier = profileConfig.fileTypeMultipliers.impl;
     // ✅ Use longest-prefix-match logic (order-independent)
     const pathBoost = getPathMultiplier(path, profileConfig);
@@ -1016,16 +2113,21 @@ function applyFileTypeMultipliers(candidate, path, ext, profileConfig, _weights)
     }
 }
 /**
- * contextBundle専用のブーストプロファイル適用（v0.7.0+: リファクタリング版）
+ * contextBundle専用のブーストプロファイル適用（v1.0.0: 乗算ペナルティモデル）
  * 複雑度を削減するために3つのヘルパー関数に分割：
  * 1. applyPathBasedScoring: パスベースの加算的スコアリング
- * 2. applyAdditiveFilePenalties: 強力な加算的ペナルティ
- * 3. applyFileTypeMultipliers: 乗算的ペナルティ/ブースト
+ * 2. applyMultiplicativeFilePenalties: 乗算的ペナルティ（blacklist/test/lock）
+ * 3. applyFileTypeMultipliers: 乗算的ペナルティ/ブースト（doc/config/impl）
  *
- * CRITICAL SAFETY RULES:
- * 1. Multipliers are stored in candidate.scoreMultiplier, applied AFTER all additive scoring
- * 2. profile="docs" skips documentation penalties (allows doc-focused queries)
- * 3. Blacklist/test/lock/config files keep additive penalties (already very strong)
+ * v1.0.0 CHANGES:
+ * - 絶対ペナルティ(-100)を乗算ペナルティ(×0.01など)に置き換え
+ * - すべてのペナルティが組み合わせ可能に（boost_profileとの相互作用が予測可能）
+ * - v0.9.0の特別ケース処理（if profile === "docs"）が不要に
+ *
+ * SCORING PHASES:
+ * 1. Additive phase: テキストマッチ、パスマッチ、依存関係、近接性を加算
+ * 2. Multiplicative phase: ペナルティとブーストを scoreMultiplier に蓄積
+ * 3. Final application: score *= scoreMultiplier（最終段階で一度だけ適用）
  */
 function applyBoostProfile(candidate, row, profileConfig, weights, extractedTerms) {
     const { path, ext } = row;
@@ -1033,117 +2135,205 @@ function applyBoostProfile(candidate, row, profileConfig, weights, extractedTerm
     const fileName = path.split("/").pop() ?? "";
     // Step 1: パスベースのスコアリング（加算的ブースト）
     applyPathBasedScoring(candidate, lowerPath, weights, extractedTerms);
-    // Step 2: 加算的ペナルティ（ブラックリスト、テスト、lock、設定、マイグレーション）
-    const shouldStop = applyAdditiveFilePenalties(candidate, path, lowerPath, fileName, profileConfig);
-    if (shouldStop) {
-        return; // ペナルティが適用された場合は処理終了
-    }
+    // Step 2: 乗算的ペナルティ（ブラックリスト、テスト、lock）
+    // v1.0.0: Returns true if severe penalty applied (should skip further boosts)
+    const skipFurtherBoosts = applyMultiplicativeFilePenalties(candidate, path, lowerPath, fileName, weights, profileConfig);
     // Step 3: ファイルタイプ別の乗算的ペナルティ/ブースト
-    applyFileTypeMultipliers(candidate, path, ext, profileConfig, weights);
+    // Skip if severe penalty was applied (blacklist/test/lock files shouldn't get impl boosts)
+    if (!skipFurtherBoosts) {
+        applyFileTypeMultipliers(candidate, path, ext, profileConfig, weights);
+    }
 }
 export async function filesSearch(context, params) {
     const { db, repoId } = context;
-    const { query } = params;
-    if (!query || query.trim().length === 0) {
-        throw new Error("files_search requires a non-empty query. Provide a search keyword to continue.");
+    const rawQuery = params.query ?? "";
+    const inlineMetadata = parseInlineMetadataFilters(rawQuery);
+    const paramFilters = normalizeMetadataFiltersParam(params.metadata_filters);
+    const metadataFilters = mergeMetadataFilters([...inlineMetadata.filters, ...paramFilters]);
+    const strictMetadataFilters = metadataFilters.filter((filter) => filter.strict);
+    const hintMetadataFilters = metadataFilters.filter((filter) => !filter.strict);
+    const hasStrictMetadataFilters = strictMetadataFilters.length > 0;
+    const hasHintMetadataFilters = hintMetadataFilters.length > 0;
+    const hasAnyMetadataFilters = metadataFilters.length > 0;
+    let cleanedQuery = inlineMetadata.cleanedQuery;
+    let hasTextQuery = cleanedQuery.length > 0;
+    if (!hasTextQuery && hasHintMetadataFilters) {
+        cleanedQuery = hintMetadataFilters
+            .flatMap((filter) => filter.values)
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)
+            .join(" ");
+        cleanedQuery = cleanedQuery.trim();
+        hasTextQuery = cleanedQuery.length > 0;
+    }
+    const metadataValueSeed = metadataFilters
+        .flatMap((filter) => filter.values)
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)
+        .join(" ");
+    if (metadataValueSeed.length > 0) {
+        cleanedQuery = `${cleanedQuery} ${metadataValueSeed}`.trim();
+        hasTextQuery = cleanedQuery.length > 0;
+    }
+    if (!hasTextQuery && !hasAnyMetadataFilters) {
+        throw new Error("files_search requires a query or metadata_filters. Provide keywords or structured filters to continue.");
     }
     const limit = normalizeLimit(params.limit);
     const ftsStatus = await getFreshFtsStatus(context);
     const hasFTS = ftsStatus.ready;
-    let sql;
-    let values;
-    if (hasFTS) {
-        // FTS拡張利用可能: fts_main_blob.match_bm25 を使用
-        const conditions = ["f.repo_id = ?"];
-        values = [repoId];
-        // 言語・拡張子フィルタ
-        if (params.lang) {
-            conditions.push("COALESCE(f.lang, '') = ?");
-            values.push(params.lang);
-        }
-        if (params.ext) {
-            conditions.push("COALESCE(f.ext, '') = ?");
-            values.push(params.ext);
-        }
-        if (params.path_prefix) {
-            conditions.push("f.path LIKE ?");
-            values.push(`${params.path_prefix}%`);
-        }
-        // FTS検索（BM25スコアリング）
-        sql = `
-      SELECT f.path, f.lang, f.ext, b.content, fts.score
-      FROM file f
-      JOIN blob b ON b.hash = f.blob_hash
-      JOIN (
-        SELECT hash, fts_main_blob.match_bm25(hash, ?) AS score
-        FROM blob
-        WHERE score IS NOT NULL
-      ) fts ON fts.hash = b.hash
-      WHERE ${conditions.join(" AND ")}
-      ORDER BY fts.score DESC
-      LIMIT ?
-    `;
-        values.unshift(query); // FTSクエリを先頭に追加
-        values.push(limit);
-    }
-    else {
-        // FTS拡張利用不可: ILIKE検索（Phase 1の単語分割ロジック）
-        const conditions = ["f.repo_id = ?", "b.content IS NOT NULL"];
-        values = [repoId];
-        const words = splitQueryWords(query);
-        if (words.length === 1) {
-            conditions.push("b.content ILIKE '%' || ? || '%'");
-            values.push(query);
+    const metadataClauses = buildMetadataFilterConditions(strictMetadataFilters);
+    const candidateRows = [];
+    if (hasTextQuery) {
+        let sql;
+        let values;
+        if (hasFTS) {
+            const conditions = ["f.repo_id = ?"];
+            values = [repoId];
+            if (params.lang) {
+                conditions.push("COALESCE(f.lang, '') = ?");
+                values.push(params.lang);
+            }
+            if (params.ext) {
+                conditions.push("COALESCE(f.ext, '') = ?");
+                values.push(params.ext);
+            }
+            if (params.path_prefix) {
+                conditions.push("f.path LIKE ?");
+                values.push(`${params.path_prefix}%`);
+            }
+            for (const clause of metadataClauses) {
+                conditions.push(clause.sql);
+                values.push(...clause.params);
+            }
+            sql = `
+        SELECT f.path, f.lang, f.ext, b.content, fts.score
+        FROM file f
+        JOIN blob b ON b.hash = f.blob_hash
+        JOIN (
+          SELECT hash, fts_main_blob.match_bm25(hash, ?) AS score
+          FROM blob
+          WHERE score IS NOT NULL
+        ) fts ON fts.hash = b.hash
+        WHERE ${conditions.join(" AND ")}
+        ORDER BY fts.score DESC
+        LIMIT ?
+      `;
+            values.unshift(cleanedQuery);
+            values.push(limit);
         }
         else {
-            const wordConditions = words.map(() => "b.content ILIKE '%' || ? || '%'");
-            conditions.push(`(${wordConditions.join(" OR ")})`);
-            values.push(...words);
-        }
-        if (params.lang) {
-            conditions.push("COALESCE(f.lang, '') = ?");
-            values.push(params.lang);
-        }
-        if (params.ext) {
-            conditions.push("COALESCE(f.ext, '') = ?");
-            values.push(params.ext);
-        }
-        if (params.path_prefix) {
-            conditions.push("f.path LIKE ?");
-            values.push(`${params.path_prefix}%`);
-        }
-        sql = `
-      SELECT f.path, f.lang, f.ext, b.content
-      FROM file f
-      JOIN blob b ON b.hash = f.blob_hash
-      WHERE ${conditions.join(" AND ")}
-      ORDER BY f.path
-      LIMIT ?
-    `;
-        values.push(limit);
-    }
-    const rows = await db.all(sql, values);
-    const boostProfile = params.boost_profile ?? "default";
-    const profileConfig = getBoostProfile(boostProfile);
-    // ✅ v0.7.0+: Load configurable scoring weights for unified boosting logic
-    // Note: filesSearch doesn't have a separate profile parameter, uses default weights
+            const conditions = ["f.repo_id = ?", "b.content IS NOT NULL"];
+            values = [repoId];
+            const words = splitQueryWords(cleanedQuery);
+            if (words.length === 1) {
+                conditions.push("b.content ILIKE '%' || ? || '%'");
+                values.push(cleanedQuery);
+            }
+            else {
+                const wordConditions = words.map(() => "b.content ILIKE '%' || ? || '%'");
+                conditions.push(`(${wordConditions.join(" OR ")})`);
+                values.push(...words);
+            }
+            if (params.lang) {
+                conditions.push("COALESCE(f.lang, '') = ?");
+                values.push(params.lang);
+            }
+            if (params.ext) {
+                conditions.push("COALESCE(f.ext, '') = ?");
+                values.push(params.ext);
+            }
+            if (params.path_prefix) {
+                conditions.push("f.path LIKE ?");
+                values.push(`${params.path_prefix}%`);
+            }
+            for (const clause of metadataClauses) {
+                conditions.push(clause.sql);
+                values.push(...clause.params);
+            }
+            sql = `
+        SELECT f.path, f.lang, f.ext, b.content
+        FROM file f
+        JOIN blob b ON b.hash = f.blob_hash
+        WHERE ${conditions.join(" AND ")}
+        ORDER BY f.path
+        LIMIT ?
+      `;
+            values.push(limit);
+        }
+        const textRows = await db.all(sql, values);
+        candidateRows.push(...textRows);
+    }
+    if (!hasTextQuery && hasAnyMetadataFilters) {
+        const metadataOnlyRows = await fetchMetadataOnlyCandidates(db, context.tableAvailability, repoId, metadataFilters, limit * 2);
+        for (const row of metadataOnlyRows) {
+            row.score = 1 + metadataFilters.length * 0.2;
+        }
+        candidateRows.push(...metadataOnlyRows);
+    }
+    if (hasTextQuery) {
+        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);
+            candidateRows.push(...metadataRows);
+        }
+    }
+    if (candidateRows.length === 0) {
+        return [];
+    }
+    const rowMap = new Map();
+    for (const row of candidateRows) {
+        const base = row.score ?? (hasTextQuery ? 1.0 : 0.8);
+        const existing = rowMap.get(row.path);
+        const existingScore = existing?.score ?? (hasTextQuery ? 1.0 : 0.8);
+        if (!existing || base > existingScore) {
+            rowMap.set(row.path, { ...row, score: base });
+        }
+    }
+    const dedupedRows = Array.from(rowMap.values()).sort((a, b) => (b.score ?? 1) - (a.score ?? 1));
+    const limitedRows = dedupedRows.slice(0, limit);
+    const paths = limitedRows.map((row) => row.path);
+    const metadataMap = await loadMetadataForPaths(db, context.tableAvailability, repoId, paths);
+    const inboundCounts = await loadInboundLinkCounts(db, context.tableAvailability, repoId, paths);
+    const metadataKeywordSet = hasTextQuery
+        ? new Set(splitQueryWords(cleanedQuery.toLowerCase()).map((kw) => kw.toLowerCase()))
+        : new Set();
+    const filterValueSet = new Set(metadataFilters.flatMap((filter) => filter.values.map((value) => value.toLowerCase())));
+    const boostProfile = params.boost_profile ??
+        (hasHintMetadataFilters ? "balanced" : hasStrictMetadataFilters ? "docs" : "default");
+    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);
-    return rows
+    const previewQuery = hasTextQuery
+        ? cleanedQuery
+        : (metadataFilters[0]?.values[0] ?? rawQuery.trim());
+    return limitedRows
         .map((row) => {
         let preview;
         let matchLine;
+        const previewSource = previewQuery || row.path;
         if (options.includePreview) {
-            // Full preview generation for non-compact mode
-            const previewData = buildPreview(row.content ?? "", query);
+            const previewData = buildPreview(row.content ?? "", previewSource);
             preview = previewData.preview;
             matchLine = previewData.line;
         }
         else {
-            // Lightweight: extract only line number without preview
-            matchLine = findFirstMatchLine(row.content ?? "", query);
+            matchLine = findFirstMatchLine(row.content ?? "", previewSource);
         }
-        const baseScore = row.score ?? 1.0; // FTS時はBM25スコア、ILIKE時は1.0
+        const metadataEntries = metadataMap.get(row.path);
+        const metadataBoost = computeMetadataBoost(metadataEntries, metadataKeywordSet, filterValueSet);
+        const inboundBoost = computeInboundLinkBoost(inboundCounts.get(row.path));
+        const baseScore = (row.score ?? (hasTextQuery ? 1.0 : 0.8)) + metadataBoost + inboundBoost;
         const boostedScore = boostProfile === "none"
             ? baseScore
             : applyFileTypeBoost(row.path, baseScore, profileConfig, weights);
@@ -1159,96 +2349,20 @@ export async function filesSearch(context, params) {
         }
         return result;
     })
-        .sort((a, b) => b.score - a.score); // スコアの高い順に再ソート
-}
-export async function snippetsGet(context, params) {
-    const { db, repoId } = context;
-    if (!params.path) {
-        throw new Error("snippets_get requires a file path. Specify a tracked text file path to continue.");
-    }
-    const rows = await db.all(`
-      SELECT f.path, f.lang, f.ext, f.is_binary, b.content
-      FROM file f
-      JOIN blob b ON b.hash = f.blob_hash
-      WHERE f.repo_id = ? AND f.path = ?
-      LIMIT 1
-    `, [repoId, params.path]);
-    if (rows.length === 0) {
-        throw new Error("Requested snippet file was not indexed. Re-run the indexer or choose another path.");
-    }
-    const row = rows[0];
-    if (!row) {
-        throw new Error("Requested snippet file was not indexed. Re-run the indexer or choose another path.");
-    }
-    if (row.is_binary) {
-        throw new Error("Binary snippets are not supported. Choose a text file to preview its content.");
-    }
-    if (row.content === null) {
-        throw new Error("Snippet content is unavailable. Re-run the indexer to refresh DuckDB state.");
-    }
-    const lines = row.content.split(/\r?\n/);
-    const totalLines = lines.length;
-    const snippetRows = await db.all(`
-      SELECT s.snippet_id, s.start_line, s.end_line, s.symbol_id, sym.name AS symbol_name, sym.kind AS symbol_kind
-      FROM snippet s
-      LEFT JOIN symbol sym
-        ON sym.repo_id = s.repo_id
-       AND sym.path = s.path
-       AND sym.symbol_id = s.symbol_id
-      WHERE s.repo_id = ? AND s.path = ?
-      ORDER BY s.start_line
-    `, [repoId, params.path]);
-    const requestedStart = params.start_line ?? 1;
-    const requestedEnd = params.end_line ?? Math.min(totalLines, requestedStart + DEFAULT_SNIPPET_WINDOW - 1);
-    const useSymbolSnippets = snippetRows.length > 0 && params.end_line === undefined;
-    let snippetSelection = null;
-    if (useSymbolSnippets) {
-        snippetSelection =
-            snippetRows.find((snippet) => requestedStart >= snippet.start_line && requestedStart <= snippet.end_line) ?? null;
-        if (!snippetSelection) {
-            const firstSnippet = snippetRows[0];
-            if (firstSnippet && requestedStart < firstSnippet.start_line) {
-                snippetSelection = firstSnippet;
-            }
-            else {
-                snippetSelection = snippetRows[snippetRows.length - 1] ?? null;
-            }
-        }
-    }
-    let startLine;
-    let endLine;
-    let symbolName = null;
-    let symbolKind = null;
-    if (snippetSelection) {
-        startLine = snippetSelection.start_line;
-        endLine = snippetSelection.end_line;
-        symbolName = snippetSelection.symbol_name;
-        symbolKind = snippetSelection.symbol_kind;
-    }
-    else {
-        startLine = Math.max(1, Math.min(totalLines, requestedStart));
-        endLine = Math.max(startLine, Math.min(totalLines, requestedEnd));
-    }
-    const isCompact = params.compact === true;
-    const addLineNumbers = params.includeLineNumbers === true && !isCompact;
-    let content;
-    if (!isCompact) {
-        const snippetContent = lines.slice(startLine - 1, endLine).join("\n");
-        content = addLineNumbers ? prependLineNumbers(snippetContent, startLine) : snippetContent;
-    }
-    return {
-        path: row.path,
-        startLine,
-        endLine,
-        ...(content !== undefined && { content }),
-        totalLines,
-        symbolName,
-        symbolKind,
-    };
+        .filter((result) => result.score > SCORE_FILTER_THRESHOLD) // v1.0.0: Filter out extremely low-scored files (multiplicative penalties)
+        .sort((a, b) => b.score - a.score);
 }
+// snippetsGet has been extracted to ./handlers/snippets-get.ts and re-exported above
 // ============================================================================
 // Issue #68: Path/Large File Penalty Helper Functions
 // ============================================================================
+/**
+ * v1.0.0: Score filtering threshold for multiplicative penalty model
+ * Files with score < threshold are filtered out (unless they are hint paths)
+ * Default: 0.05 removes files with >95% penalty while keeping relevant files
+ * Can be overridden via KIRI_SCORE_THRESHOLD environment variable
+ */
+const SCORE_FILTER_THRESHOLD = parseFloat(process.env.KIRI_SCORE_THRESHOLD ?? "0.05");
 /**
  * 環境変数からペナルティ機能フラグを読み取る
  */
@@ -1505,15 +2619,40 @@ function computeGraduatedPenalty(pathMatchHits, queryStats, config) {
         return config.tier2Delta;
     return 0; // pathMatchHits >= 3: no penalty
 }
-export async function contextBundle(context, params) {
+async function contextBundleImpl(context, params) {
     context.warningManager.startRequest();
     const { db, repoId } = context;
-    const goal = params.goal?.trim() ?? "";
-    if (goal.length === 0) {
+    const rawGoal = params.goal?.trim() ?? "";
+    if (rawGoal.length === 0) {
         throw new Error("context_bundle requires a non-empty goal. Describe your objective to receive context.");
     }
+    if (process.env.KIRI_TRACE_METADATA === "1") {
+        console.info(`[metadata-trace-env] goal=${rawGoal}`);
+    }
+    const inlineMetadata = parseInlineMetadataFilters(rawGoal);
+    const paramFilters = normalizeMetadataFiltersParam(params.metadata_filters);
+    const metadataFilters = mergeMetadataFilters([...inlineMetadata.filters, ...paramFilters]);
+    const strictMetadataFilters = metadataFilters.filter((filter) => filter.strict);
+    const hintMetadataFilters = metadataFilters.filter((filter) => !filter.strict);
+    const hasStrictMetadataFilters = strictMetadataFilters.length > 0;
+    const hasHintMetadataFilters = hintMetadataFilters.length > 0;
+    const hasAnyMetadataFilters = metadataFilters.length > 0;
+    const goal = inlineMetadata.cleanedQuery.length > 0 ? inlineMetadata.cleanedQuery : rawGoal;
+    if (process.env.KIRI_TRACE_METADATA === "1") {
+        console.info("[metadata-trace]", JSON.stringify({
+            rawGoal,
+            cleanedGoal: goal,
+            inlineFilters: inlineMetadata.filters,
+            paramFilters,
+            mergedFilters: metadataFilters,
+        }));
+    }
     const limit = normalizeBundleLimit(params.limit);
     const artifacts = params.artifacts ?? {};
+    const artifactHints = normalizeArtifactHints(artifacts.hints);
+    const hintBuckets = bucketArtifactHints(artifactHints);
+    const artifactPathHints = hintBuckets.pathHints;
+    const substringHints = hintBuckets.substringHints;
     const includeTokensEstimate = params.includeTokensEstimate === true;
     const isCompact = params.compact === true;
     // 項目2: トークンバジェット保護警告
@@ -1536,9 +2675,20 @@ export async function contextBundle(context, params) {
     if (artifacts.editing_path) {
         keywordSources.push(artifacts.editing_path);
     }
+    if (artifactHints.length > 0) {
+        keywordSources.push(artifactHints.join(" "));
+    }
+    if (hasAnyMetadataFilters) {
+        const filterSeed = metadataFilters
+            .map((filter) => `${filter.source ?? "meta"}:${filter.key}=${filter.values.join(",")}`)
+            .join(" ");
+        keywordSources.push(filterSeed);
+    }
     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 &&
@@ -1553,13 +2703,20 @@ export async function contextBundle(context, params) {
     const stringMatchSeeds = new Set();
     const fileCache = new Map();
     // ✅ Cache boost profile config to avoid redundant lookups in hot path
-    const boostProfile = params.boost_profile ?? "default";
-    const profileConfig = getBoostProfile(boostProfile);
+    const boostProfile = params.boost_profile ??
+        (hasHintMetadataFilters ? "balanced" : hasStrictMetadataFilters ? "docs" : "default");
+    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
+        traceSearch(`Executing phrase match query with repo_id=${repoId}, phrases=${JSON.stringify(extractedTerms.phrases)}`);
         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
@@ -1573,6 +2730,17 @@ export async function contextBundle(context, params) {
         ORDER BY f.path
         LIMIT ?
       `, [repoId, ...extractedTerms.phrases, MAX_MATCHES_PER_KEYWORD * extractedTerms.phrases.length]);
+        // DEBUG: Log returned paths and verify they match expected repo_id
+        if (rows.length > 0) {
+            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);
+            traceSearch(`Repo ID verification`, verification);
+        }
         for (const row of rows) {
             if (row.content === null) {
                 continue;
@@ -1584,6 +2752,7 @@ export async function contextBundle(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倍のスコア
@@ -1614,6 +2783,7 @@ export async function contextBundle(context, params) {
                 });
             }
         }
+        traceSearch(`phrase search produced ${rows.length} rows, candidates=${candidates.size}`);
     }
     // キーワードマッチング（通常の重み）- 統合クエリでパフォーマンス改善
     if (extractedTerms.keywords.length > 0) {
@@ -1648,6 +2818,7 @@ export async function contextBundle(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") {
@@ -1673,6 +2844,124 @@ export async function contextBundle(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 dictionaryPathTargets = await fetchDictionaryPathHints(db, context.tableAvailability, repoId, substringHints, HINT_DICTIONARY_LIMIT);
+    const { list: resolvedPathHintTargets, meta: hintSeedMeta } = createHintSeedMeta([
+        ...artifactPathTargets,
+        ...dictionaryPathTargets,
+    ]);
+    if (resolvedPathHintTargets.length > 0) {
+        await applyPathHintPromotions({
+            db,
+            tableAvailability: context.tableAvailability,
+            repoId,
+            hintTargets: resolvedPathHintTargets,
+            candidates,
+            fileCache,
+            weights,
+            hintSeedMeta,
+        });
+    }
+    if (substringHints.length > 0) {
+        await addHintSubstringMatches(db, context.tableAvailability, repoId, substringHints, candidates, HINT_SUBSTRING_LIMIT, HINT_SUBSTRING_BOOST);
     }
     if (artifacts.editing_path) {
         const editingCandidate = ensureCandidate(candidates, artifacts.editing_path);
@@ -1681,7 +2970,6 @@ export async function contextBundle(context, params) {
         editingCandidate.matchLine ??= 1;
     }
     // SQL injection防御: ファイルパスの検証パターン
-    const SAFE_PATH_PATTERN = /^[a-zA-Z0-9_.\-/]+$/;
     const dependencySeeds = new Set();
     for (const pathSeed of stringMatchSeeds) {
         if (!SAFE_PATH_PATTERN.test(pathSeed)) {
@@ -1695,10 +2983,13 @@ export async function contextBundle(context, params) {
     }
     if (artifacts.editing_path) {
         if (!SAFE_PATH_PATTERN.test(artifacts.editing_path)) {
-            throw new Error(`Invalid editing_path format. Path must contain only alphanumeric characters, underscores, dots, hyphens, and forward slashes.`);
+            throw new Error(`Invalid editing_path format: ${artifacts.editing_path}. Use only A-Z, 0-9, _, ., -, / characters.`);
         }
         dependencySeeds.add(artifacts.editing_path);
     }
+    for (const target of resolvedPathHintTargets) {
+        dependencySeeds.add(target.path);
+    }
     if (dependencySeeds.size > 0) {
         // SQL injection防御: プレースホルダー生成前にサイズを検証
         if (dependencySeeds.size > MAX_DEPENDENCY_SEEDS_QUERY_LIMIT) {
@@ -1708,7 +2999,7 @@ export async function contextBundle(context, params) {
         // 防御的チェック: プレースホルダーが正しい形式であることを確認
         // 期待される形式: "?, ?, ..." (クエスチョンマーク、カンマ、スペースのみ)
         if (!/^(\?)(,\s*\?)*$/.test(placeholders)) {
-            throw new Error("Invalid placeholder generation detected. Operation aborted for safety.");
+            throw new Error("Invalid dependency placeholder sequence detected. Remove unsafe dependency seeds and retry the request.");
         }
         const depRows = await db.all(`
         SELECT src_path, dst_kind, dst, rel
@@ -1746,31 +3037,74 @@ export async function contextBundle(context, params) {
             }
         }
     }
-    const materializedCandidates = [];
-    for (const candidate of candidates.values()) {
-        if (!candidate.content) {
-            const cached = fileCache.get(candidate.path);
-            if (cached) {
-                candidate.content = cached.content;
-                candidate.lang = cached.lang;
-                candidate.ext = cached.ext;
-                candidate.totalLines = cached.totalLines;
-                candidate.embedding = cached.embedding;
+    const materializeCandidates = async () => {
+        const result = [];
+        for (const candidate of candidates.values()) {
+            if (isSuppressedPath(candidate.path)) {
+                continue;
             }
-            else {
-                const loaded = await loadFileContent(db, repoId, candidate.path);
-                if (!loaded) {
-                    continue;
+            if (!candidate.content) {
+                const cached = fileCache.get(candidate.path);
+                if (cached) {
+                    candidate.content = cached.content;
+                    candidate.lang = cached.lang;
+                    candidate.ext = cached.ext;
+                    candidate.totalLines = cached.totalLines;
+                    candidate.embedding = cached.embedding;
                 }
-                candidate.content = loaded.content;
-                candidate.lang = loaded.lang;
-                candidate.ext = loaded.ext;
-                candidate.totalLines = loaded.totalLines;
-                candidate.embedding = loaded.embedding;
-                fileCache.set(candidate.path, loaded);
+                else {
+                    const loaded = await loadFileContent(db, repoId, candidate.path);
+                    if (!loaded) {
+                        continue;
+                    }
+                    candidate.content = loaded.content;
+                    candidate.lang = loaded.lang;
+                    candidate.ext = loaded.ext;
+                    candidate.totalLines = loaded.totalLines;
+                    candidate.embedding = loaded.embedding;
+                    fileCache.set(candidate.path, loaded);
+                }
+            }
+            result.push(candidate);
+        }
+        return result;
+    };
+    const addMetadataFallbackCandidates = async () => {
+        if (!hasAnyMetadataFilters) {
+            return;
+        }
+        const metadataRows = await fetchMetadataOnlyCandidates(db, context.tableAvailability, repoId, metadataFilters, limit * 2);
+        if (metadataRows.length === 0) {
+            return;
+        }
+        for (const row of metadataRows) {
+            const candidate = ensureCandidate(candidates, row.path);
+            if (row.content) {
+                candidate.content = row.content;
+                candidate.totalLines = row.content.split(/\r?\n/).length;
+                fileCache.set(row.path, {
+                    content: row.content,
+                    lang: row.lang,
+                    ext: row.ext,
+                    totalLines: candidate.totalLines,
+                    embedding: candidate.embedding,
+                });
             }
+            candidate.lang ??= row.lang;
+            candidate.ext ??= row.ext;
+            candidate.matchLine ??= 1;
+            candidate.score = Math.max(candidate.score, 1 + metadataFilters.length * 0.2);
         }
-        materializedCandidates.push(candidate);
+    };
+    if (hasAnyMetadataFilters) {
+        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)
@@ -1781,6 +3115,72 @@ export async function contextBundle(context, params) {
             ...(warnings.length > 0 && { warnings }),
         };
     }
+    const metadataKeywordSet = new Set(extractedTerms.keywords.map((keyword) => keyword.toLowerCase()));
+    const filterValueSet = new Set(metadataFilters.flatMap((filter) => filter.values.map((value) => value.toLowerCase())));
+    let metadataEntriesMap;
+    if (hasAnyMetadataFilters || metadataKeywordSet.size > 0 || filterValueSet.size > 0) {
+        metadataEntriesMap = await loadMetadataForPaths(db, context.tableAvailability, repoId, materializedCandidates.map((candidate) => candidate.path));
+    }
+    if (hasStrictMetadataFilters) {
+        metadataEntriesMap ??= new Map();
+        for (let i = materializedCandidates.length - 1; i >= 0; i--) {
+            const candidate = materializedCandidates[i];
+            if (!candidate) {
+                continue; // Skip undefined entries
+            }
+            const entries = metadataEntriesMap.get(candidate.path);
+            const matchesFilters = candidateMatchesMetadataFilters(entries, strictMetadataFilters);
+            if (!matchesFilters) {
+                materializedCandidates.splice(i, 1);
+                continue;
+            }
+            candidate.reasons.add("metadata:filter");
+            if (process.env.KIRI_TRACE_METADATA === "1") {
+                console.info(`[metadata-trace-match] path=${candidate.path}`);
+            }
+        }
+        if (materializedCandidates.length === 0 && hasAnyMetadataFilters) {
+            await addMetadataFallbackCandidates();
+            materializedCandidates = await materializeCandidates();
+        }
+        if (materializedCandidates.length === 0) {
+            const warnings = [...context.warningManager.responseWarnings];
+            return {
+                context: [],
+                ...(includeTokensEstimate && { tokens_estimate: 0 }),
+                ...(warnings.length > 0 && { warnings }),
+            };
+        }
+    }
+    if (hasHintMetadataFilters) {
+        metadataEntriesMap ??= new Map();
+        for (const candidate of materializedCandidates) {
+            const entries = metadataEntriesMap.get(candidate.path);
+            const matchesHints = candidateMatchesMetadataFilters(entries, hintMetadataFilters);
+            if (matchesHints) {
+                candidate.score += METADATA_HINT_BONUS;
+                candidate.reasons.add("metadata:hint");
+            }
+        }
+    }
+    const inboundCounts = await loadInboundLinkCounts(db, context.tableAvailability, repoId, materializedCandidates.map((candidate) => candidate.path));
+    if (metadataEntriesMap) {
+        for (const candidate of materializedCandidates) {
+            const entries = metadataEntriesMap.get(candidate.path);
+            const metadataBoost = computeMetadataBoost(entries, metadataKeywordSet, filterValueSet);
+            if (metadataBoost > 0) {
+                candidate.score += metadataBoost;
+                candidate.reasons.add("boost:metadata");
+            }
+        }
+    }
+    for (const candidate of materializedCandidates) {
+        const linkBoost = computeInboundLinkBoost(inboundCounts.get(candidate.path));
+        if (linkBoost > 0) {
+            candidate.score += linkBoost;
+            candidate.reasons.add("boost:links");
+        }
+    }
     applyStructuralScores(materializedCandidates, queryEmbedding, weights.structural);
     // ✅ CRITICAL SAFETY: Apply multipliers AFTER all additive scoring (v0.7.0)
     // Only apply to positive scores to prevent negative score inversion
@@ -1819,18 +3219,39 @@ export async function contextBundle(context, params) {
         const telemetry = computePenaltyTelemetry(materializedCandidates);
         logPenaltyTelemetry(telemetry, queryStats);
     }
-    const sortedCandidates = materializedCandidates
-        .filter((candidate) => candidate.score > 0) // Filter out candidates with negative or zero scores
+    // v1.0.0: Filter out extremely low-scored candidates (result of multiplicative penalties)
+    // Threshold removes files with >95% penalty while keeping reasonably relevant files
+    // Hint paths are exempt from this threshold (always included if score > 0)
+    const hintPathSet = new Set(resolvedPathHintTargets.map((target) => target.path));
+    const rankedCandidates = materializedCandidates
+        .filter((candidate) => candidate.score > SCORE_FILTER_THRESHOLD ||
+        (candidate.score > 0 && hintPathSet.has(candidate.path)))
         .sort((a, b) => {
         if (b.score === a.score) {
             return a.path.localeCompare(b.path);
         }
         return b.score - a.score;
-    })
-        .slice(0, limit);
-    const maxScore = Math.max(...sortedCandidates.map((candidate) => candidate.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];
+        return {
+            context: [],
+            ...(includeTokensEstimate && { tokens_estimate: 0 }),
+            ...(warnings.length > 0 && { warnings }),
+        };
+    }
+    const maxScore = Math.max(...prioritizedCandidates.map((candidate) => candidate.score));
     const results = [];
-    for (const candidate of sortedCandidates) {
+    for (const candidate of prioritizedCandidates) {
         if (!candidate.content) {
             continue;
         }
@@ -1858,6 +3279,23 @@ export async function contextBundle(context, params) {
             startLine = Math.max(1, matchLine - windowHalf);
             endLine = Math.min(totalLines === 0 ? matchLine + windowHalf : totalLines, startLine + FALLBACK_SNIPPET_WINDOW - 1);
         }
+        if (CLAMP_SNIPPETS_ENABLED) {
+            // Clamp snippet length to FALLBACK_SNIPPET_WINDOW even when symbol spans large regions
+            const maxWindow = FALLBACK_SNIPPET_WINDOW;
+            const selectedEnd = selected ? selected.end_line : endLine;
+            const selectedStart = selected ? selected.start_line : startLine;
+            if (endLine - startLine + 1 > maxWindow) {
+                const anchor = candidate.matchLine ?? startLine;
+                let clampedStart = Math.max(selectedStart, anchor - Math.floor(maxWindow / 2));
+                let clampedEnd = clampedStart + maxWindow - 1;
+                if (clampedEnd > selectedEnd) {
+                    clampedEnd = selectedEnd;
+                    clampedStart = Math.max(selectedStart, clampedEnd - maxWindow + 1);
+                }
+                startLine = clampedStart;
+                endLine = Math.max(clampedStart, clampedEnd);
+            }
+        }
         if (endLine < startLine) {
             endLine = startLine;
         }
@@ -1885,7 +3323,7 @@ export async function contextBundle(context, params) {
     let tokensEstimate;
     if (includeTokensEstimate) {
         tokensEstimate = results.reduce((acc, item) => {
-            const candidate = sortedCandidates.find((c) => c.path === item.path);
+            const candidate = prioritizedCandidates.find((c) => c.path === item.path);
             if (candidate && candidate.content) {
                 return acc + estimateTokensFromContent(candidate.content, item.range[0], item.range[1]);
             }
@@ -1896,8 +3334,13 @@ export async function contextBundle(context, params) {
     }
     // Get warnings from WarningManager (includes breaking change notification if applicable)
     const warnings = [...context.warningManager.responseWarnings];
+    const shouldFilterResults = FINAL_RESULT_SUPPRESSION_ENABLED && SUPPRESS_NON_CODE_ENABLED;
+    const sanitizedResults = shouldFilterResults
+        ? results.filter((item) => !isSuppressedPath(item.path))
+        : results;
+    const finalResults = sanitizedResults.length > 0 ? sanitizedResults : results;
     const payload = {
-        context: results,
+        context: finalResults,
         ...(warnings.length > 0 && { warnings }),
     };
     if (tokensEstimate !== undefined) {
@@ -2100,35 +3543,27 @@ export async function depsClosure(context, params) {
         edges,
     };
 }
-export async function resolveRepoId(db, repoRoot) {
+/**
+ * リポジトリのrootパスをデータベースIDに解決する。
+ *
+ * この関数は下位互換性のために保持されているが、内部的には新しいRepoResolverを使用する。
+ *
+ * @param db - DuckDBクライアント
+ * @param repoRoot - リポジトリのrootパス
+ * @param services - オプショナルなServerServices（指定がなければ新規作成される）
+ * @returns リポジトリID
+ * @throws Error リポジトリがインデックスされていない場合
+ */
+export async function resolveRepoId(db, repoRoot, services) {
+    const svc = services ?? createServerServices(db);
+    return await svc.repoResolver.resolveId(repoRoot);
+}
+export async function contextBundle(context, params) {
     try {
-        const candidates = getRepoPathCandidates(repoRoot);
-        const normalized = candidates[0];
-        const placeholders = candidates.map(() => "?").join(", ");
-        const rows = await db.all(`SELECT id, root FROM repo WHERE root IN (${placeholders}) LIMIT 1`, candidates);
-        if (rows.length === 0) {
-            const existingRows = await db.all("SELECT id, root FROM repo");
-            for (const candidate of existingRows) {
-                if (normalizeRepoPath(candidate.root) === normalized) {
-                    await db.run("UPDATE repo SET root = ? WHERE id = ?", [normalized, candidate.id]);
-                    return candidate.id;
-                }
-            }
-            throw new Error("Target repository is missing from DuckDB. Run the indexer before starting the server.");
-        }
-        const row = rows[0];
-        if (!row) {
-            throw new Error("Failed to retrieve repository record. Database returned empty result.");
-        }
-        if (row.root !== normalized) {
-            await db.run("UPDATE repo SET root = ? WHERE id = ?", [normalized, row.id]);
-        }
-        return row.id;
+        return await contextBundleImpl(context, params);
     }
     catch (error) {
-        if (error instanceof Error && error.message.includes("Table with name repo")) {
-            throw new Error("Target repository is missing from DuckDB. Run the indexer before starting the server.");
-        }
+        console.error("context_bundle error:", error);
         throw error;
     }
 }