graph-indexer 2.0.0 → 2.1.0

package/mcp/tools.mjs

@@ -8,17 +8,21 @@
 import { z } from 'zod';
 import fs from 'fs';
 import path, { resolve } from 'path';
-import { computePageRank, isNaturalLanguageQuery } from '../search-core.mjs';
+import { computePageRank, isNaturalLanguageQuery, TEST_FILE_RE, learnedRerank, DEFAULT_RANKER_MODEL } from '../search-core.mjs';
 import { getParserForFile } from '../parse/languages.mjs';
 import { extractFileSkeleton } from '../parse/extractor.mjs';
 import { describeEmbedder } from '../embeddings.mjs';
-import { rerankResults, ollamaGenerate, mlxLmGenerate } from '../enrichment.mjs';
+import { rerankResults, rerankCrossEncoder, crossEncoderScore, ollamaGenerate, mlxLmGenerate } from '../enrichment.mjs';
+import { encodeMultiVector, rerankLateInteraction } from '../colbert.mjs';
 import { coChangesFor, gitBoostScore, computeFreshness, currentGitState } from '../git-signals.mjs';
+import { egressGuardActive } from '../seal.mjs';
 import { extractSignatureLine, pruneBodyByQuery } from './format.mjs';
 import {
     assessConfidence, hydeQueryVector, buildHydePrompt, detectRepoLanguage,
-    classifyCallers, findReferences, findRoutes, buildSubgraph,
+    classifyCallers, findReferences, findRoutes, buildSubgraph, buildImpact,
 } from './topology.mjs';
+import { traceTaint, findTaintedSinks } from './taint.mjs';
+import { CATEGORY_SEVERITY } from '../parse/taint-patterns.mjs';
 
 // ─── Structured (JSON) output helpers ────────────────────────────────────────────
 
@@ -116,7 +120,7 @@ function refCard({ chunk, recvHint, reason, confidence }) {
  * @param {object|null} [opts.gitSignals] Loaded git-signals sidecar (churn/recency/co-change), or null.
  * @param {number} [opts.gitRankBoost]    0..1 opt-in recency/churn weight in search_code (0 = ranking unchanged).
  */
-export function registerTools(server, db, { projectRoot, artifactPath, pidFile, embeddingsEnabled, embedder, rerank, hyde, ollamaHost = 'http://localhost:11434', llmProvider = 'ollama', mlxLmHost = 'http://localhost:8080', gitSignals = null, gitRankBoost = 0 }) {
+export function registerTools(server, db, { projectRoot, artifactPath, pidFile, embeddingsEnabled, embedder, rerank, hyde, ollamaHost = 'http://localhost:11434', llmProvider = 'ollama', mlxLmHost = 'http://localhost:8080', gitSignals = null, gitRankBoost = 0, sealed = 'off', ranker = 'rrf' }) {
 
     // Scoped here (not module-level) so multiple servers in one process don't cross-contaminate.
     // `undefined` = not yet detected; `null` = unknown (→ generic prompt).
@@ -156,6 +160,25 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
         return bits.join(' · ');
     };
 
+    // ── test → code mapping (C5) ──────────────────────────────────────────────
+    // The test chunks that exercise a symbol: a test/spec chunk (TEST_FILE_RE) that
+    // either CALLS the symbol or REFERENCES it (type/inheritance). Deduped by id,
+    // deterministically ordered (file, line, id). Shared by tests_for + explain_symbol.
+    const testsForSymbol = (symbol) => {
+        const seen = new Set();
+        const out = [];
+        for (const c of [...db.findCallers(symbol), ...db.findReferers(symbol)]) {
+            if (!c || !TEST_FILE_RE.test(c.file_path) || seen.has(c.id)) continue;
+            seen.add(c.id);
+            out.push(c);
+        }
+        out.sort((a, b) =>
+            (a.file_path < b.file_path ? -1 : a.file_path > b.file_path ? 1 : 0)
+            || (a.start_line - b.start_line)
+            || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        return out;
+    };
+
     // ─── search_code ────────────────────────────────────────────────────────────
     server.tool(
         'search_code',
@@ -234,26 +257,61 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                 // in the tool layer — never in db.searchHybrid — so measured
                 // retrieval ranking and backend parity are unchanged unless enabled.
                 const applyGitBoost = gitRankBoost > 0 && gitSignals;
+                // D3: the learned re-rank also needs a deeper pool to RESCUE a structurally-strong
+                // but lexically-deep hit into top_k (same rationale as rerank / git boost).
+                const wantLearned = ranker === 'learned' && !exact_tokens;
                 const poolSize = willRerank
                     ? Math.min(Math.max(top_k, rerank?.poolSize ?? 15), 25)
-                    : applyGitBoost ? Math.min(Math.max(top_k * 2, 12), 25) : top_k;
+                    : (applyGitBoost || wantLearned) ? Math.min(Math.max(top_k * 2, 12), 25) : top_k;
                 let matches = db.searchHybrid(fullQuery, queryVector, poolSize, min_score, exact_tokens || null);
 
+                // D3: post-fusion learned re-rank (opt-in). Reorders the fused pool by a zero-dep
+                // linear model over RRF score + centrality + resolved/SCIP in-degree + git, BEFORE the
+                // optional LLM judge / git nudge. Accessors are null when the layer is absent, so the
+                // model degrades to RRF + git + node-type (≈neutral) on a plain index.
+                if (wantLearned && matches.length > 1) {
+                    matches = learnedRerank(matches, {
+                        getCentrality: db.hasCentrality?.() ? (id) => db.getCentrality(id) : null,
+                        getInEdges: db.hasSymbolGraph?.() ? (id) => db.getEdges(id, { direction: 'in' }) : null,
+                        gitScoreFor: gitSignals ? (file) => gitBoostScore(gitSignals, file) : null,
+                    }, DEFAULT_RANKER_MODEL);
+                }
+
                 let rerankFailed = false;
                 if (willRerank && matches.length > 1) {
                     try {
-                        matches = await rerankResults(fullQuery, matches, {
-                            topM: Math.min(rerank?.topM ?? 12, matches.length),
-                            generate: llmProvider === 'mlx'
-                                ? (prompt) => mlxLmGenerate(prompt, { mlxLmHost, timeoutMs: 60000 })
-                                : (prompt) => ollamaGenerate(prompt, {
-                                    model: rerank?.model || 'qwen2.5-coder:7b',
-                                    ollamaHost, timeoutMs: 60000,
-                                    options: { temperature: 0, num_predict: 40 },
-                                }),
-                        });
+                        if (rerank?.provider === 'cross-encoder') {
+                            // Local air-gapped cross-encoder: scores (query, candidate) pairs and
+                            // sorts. Reuses the same over-fetched pool; deterministic; no LLM call.
+                            matches = await rerankCrossEncoder(fullQuery, matches, {
+                                topM: Math.min(rerank?.topM ?? 12, matches.length),
+                                scorer: (q, texts) => crossEncoderScore(q, texts, { model: rerank?.crossEncoderModel }),
+                            });
+                        } else if (rerank?.provider === 'late-interaction') {
+                            // B4 ColBERT-style late interaction: encode the query into multi-vectors
+                            // with the SAME local embedder, then MaxSim-rerank against each candidate's
+                            // stored doc sub-vectors. Air-gapped, deterministic, parity-safe; a no-op
+                            // (original order) without --embeddings (no embedder / no doc vectors).
+                            const qVecs = embedder ? await encodeMultiVector(embedder, fullQuery) : [];
+                            matches = rerankLateInteraction(matches, {
+                                qVecs,
+                                binPath: db.embeddingBinPath?.(),
+                                topM: Math.min(rerank?.topM ?? 12, matches.length),
+                            });
+                        } else {
+                            matches = await rerankResults(fullQuery, matches, {
+                                topM: Math.min(rerank?.topM ?? 12, matches.length),
+                                generate: llmProvider === 'mlx'
+                                    ? (prompt) => mlxLmGenerate(prompt, { mlxLmHost, timeoutMs: 60000 })
+                                    : (prompt) => ollamaGenerate(prompt, {
+                                        model: rerank?.model || 'qwen2.5-coder:7b',
+                                        ollamaHost, timeoutMs: 60000,
+                                        options: { temperature: 0, num_predict: 40 },
+                                    }),
+                            });
+                        }
                     } catch {
-                        // An unreachable or slow judge must degrade gracefully — never
+                        // An unreachable or slow reranker must degrade gracefully — never
                         // turn the whole search into an error. `matches` retains its
                         // pre-rerank order because the throwing await never reassigned it.
                         rerankFailed = true;
@@ -774,10 +832,11 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
         },
         async ({ symbol, target_class, response_format }) => {
             try {
-                const { targetDefs, ambiguous, calls, inherits, types } =
+                const { targetDefs, ambiguous, calls, inherits, types, references } =
                     findReferences(db, symbol, { targetClass: target_class || null });
                 const callTotal = calls.high.length + calls.nameOnly.length;
                 const total = callTotal + inherits.length + types.length;
+                const scipRefs = references || [];
                 const coChanges = coChangeFiles(gitSignals, [...new Set(targetDefs.map(d => d.file_path))]);
                 const fresh = indexFreshness();
                 const note = freshnessNote(fresh);
@@ -795,12 +854,15 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                         },
                         subclassed_by: inherits.map(refCard),
                         used_as_type_by: types.map(refCard),
+                        // A2 v2: binding-precise cross-file references from a SCIP index (resolved tier).
+                        referenced_by_resolved: scipRefs.map(refCard),
+                        resolved_reference_count: scipRefs.length,
                         co_changes: coChanges,
                         index: fresh,
                     });
                 }
 
-                if (total === 0) {
+                if (total === 0 && scipRefs.length === 0) {
                     const parts = [`✅ No references to \`${symbol}\` found in the index.`];
                     if (coChanges.length) parts.push(coChangeLine(coChanges));
                     if (note) parts.push(note);
@@ -813,7 +875,8 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                     + (recvHint ? ` · via ${recvHint}` : '')
                     + (confidence === 'name-only' ? ' · ⚠️ unverified' : '');
 
-                const lines = [`# 🔗 References to \`${symbol}\` — ${total} total`];
+                const lines = [`# 🔗 References to \`${symbol}\` — ${total} total`
+                    + (scipRefs.length ? ` · ${scipRefs.length} SCIP-resolved` : '')];
                 if (ambiguous) lines.push(`⚠️ ${targetDefs.length} symbols named \`${symbol}\` — name-only matches may target a different one.`);
 
                 if (callTotal) {
@@ -829,6 +892,12 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                     lines.push('', `## 🏷  Used as a type by (${types.length})`);
                     for (const it of types) lines.push(fmt(it));
                 }
+                if (scipRefs.length) {
+                    lines.push('', `## 🎯 Referenced by — SCIP-resolved (${scipRefs.length})`,
+                        '_Binding-precise cross-file references from your SCIP index (kind-agnostic): disambiguates'
+                        + ' same-named symbols and catches uses the name heuristics above can miss._');
+                    for (const it of scipRefs) lines.push(fmt(it));
+                }
                 if (coChanges.length) lines.push('', coChangeLine(coChanges));
                 if (note) lines.push('', note);
                 return { content: [{ type: 'text', text: lines.join('\n') }] };
@@ -1000,6 +1069,11 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                 const totalFiles = fileChunks.size;
                 const totalSymbols = Array.from(fileChunks.values()).reduce((s, a) => s + a.length, 0);
 
+                // A5: most-central symbols (PageRank over the resolved symbol graph), shown only
+                // on the unfiltered orientation view and only when --symbol-graph built it.
+                // Absent on the default path → output byte-identical.
+                const central = (db.hasCentrality?.() && !path_filter) ? db.topCentral(12) : [];
+
                 if (response_format === 'json') {
                     const files = sortedFiles.map(filePath => {
                         const seen = new Set();
@@ -1019,6 +1093,14 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                     return jsonResult({
                         total_files: totalFiles, total_symbols: totalSymbols,
                         shown_files: sortedFiles.length, sort_by, path_filter: path_filter || null,
+                        ...(central.length ? {
+                            central_total: db.getCentrality(central[0].chunk.id)?.total ?? central.length,
+                            central_symbols: central.map(({ chunk, score, rank }) => ({
+                                name: chunk.name, class_context: chunk.class_context || null,
+                                file_path: chunk.file_path, node_type: chunk.node_type,
+                                rank, score,
+                            })),
+                        } : {}),
                         files,
                     });
                 }
@@ -1029,6 +1111,16 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                     sortedFiles.length < totalFiles ? `(showing top ${sortedFiles.length} by ${sort_by}; use path_filter to narrow)\n` : '',
                 ].filter(Boolean);
 
+                if (central.length) {
+                    const cenTotal = db.getCentrality(central[0].chunk.id)?.total ?? central.length;
+                    lines.push(`**Most central symbols** (PageRank over the resolved symbol graph, top ${central.length} of ${cenTotal}):`);
+                    for (const { chunk, rank } of central) {
+                        const nm = `${chunk.class_context ? chunk.class_context + '.' : ''}${chunk.name}`;
+                        lines.push(`  ${rank}. \`${nm}\` — \`${chunk.file_path}\``);
+                    }
+                    lines.push('');
+                }
+
                 for (const filePath of sortedFiles) {
                     const chunks = fileChunks.get(filePath);
                     lines.push(`\n${filePath}`);
@@ -1116,6 +1208,10 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                         embeddings_enabled: Boolean(embeddingsEnabled),
                         embedder: embedder ? { provider: embedder.provider, model: embedder.model, dim: embedder.dim ?? null } : null,
                         lazy_mode: s.lazyMode,
+                        sealed: sealed,
+                        egress_guard: sealed === 'off' ? 'off' : (egressGuardActive() ? 'active' : 'requested'),
+                        taint_flows: db.hasTaint?.() ? (db.getTaintFlows()?.flows?.length ?? 0) : null,
+                        scip_references: db.hasScipRefs?.() ? (db.scipRefCount?.() ?? null) : null,
                         daemon_running: daemonRunning,
                         index_age_seconds: ageSeconds,
                         freshness: {
@@ -1139,6 +1235,9 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
                     `| **Vector entries** | ${s.vectors} |`,
                     `| **Search mode** | ${searchMode} |`,
                     `| **Lazy vec mode** | ${s.lazyMode ? '✅ Yes (enterprise scale)' : '❌ No (small corpus)'} |`,
+                    ...(sealed !== 'off' ? [`| **Sealed mode** | 🔒 ${sealed} · egress guard ${egressGuardActive() ? 'active' : 'requested'} |`] : []),
+                    ...(db.hasTaint?.() ? [`| **Taint flows** | 🧪 ${db.getTaintFlows()?.flows?.length ?? 0} precomputed |`] : []),
+                    ...(db.hasScipRefs?.() ? [`| **SCIP references** | 🎯 ${db.scipRefCount?.() ?? 0} definitions (precise cross-file) |`] : []),
                     `| **Daemon** | ${daemonStatus} |`,
                     `| **Index age** | ${indexAge} |`,
                     `| **Built at commit** | ${fresh.indexedCommit || '—'}${fresh.commitMoved ? ` (HEAD now ${fresh.currentCommit})` : ''} |`,
@@ -1154,4 +1253,330 @@ export function registerTools(server, db, { projectRoot, artifactPath, pidFile,
             }
         }
     );
+
+    // ─── tests_for ────────────────────────────────────────────────────────────────
+    server.tool(
+        'tests_for',
+        'Find the tests that exercise a symbol — the test/spec chunks that call or reference it. '
+        + 'Use it to see how a function/class is meant to behave, or which tests to run (or update) '
+        + 'before changing it. Returns each test chunk + id (call get_chunk for the body).',
+        {
+            symbol: z.string().describe("Exact symbol name (function, class, method) to find tests for."),
+            response_format: z.enum(['markdown', 'json']).default('markdown').describe(
+                "'markdown' (default) or 'json' (typed { tests: [...] })."
+            ),
+        },
+        async ({ symbol, response_format }) => {
+            try {
+                const tests = testsForSymbol(symbol);
+                const fresh = indexFreshness();
+                const note = freshnessNote(fresh);
+
+                if (response_format === 'json') {
+                    return jsonResult({ symbol, test_count: tests.length, tests: tests.map(chunkCard), index: fresh });
+                }
+                if (tests.length === 0) {
+                    const known = db.resolveSymbol(symbol).length > 0;
+                    const parts = [known
+                        ? `🧪 No tests found that reference \`${symbol}\`. It may be untested, or its tests are dynamic/indirect (the test calls a wrapper, not the symbol directly).`
+                        : `Symbol \`${symbol}\` is not in the index. Try search_code(query="${symbol}").`];
+                    if (note) parts.push(note);
+                    return { content: [{ type: 'text', text: parts.join('\n') }] };
+                }
+                const lines = [`# 🧪 Tests for \`${symbol}\` — ${tests.length}`];
+                for (const t of tests) {
+                    lines.push(`- \`${t.class_context ? t.class_context + '.' : ''}${t.name}\` [${t.node_type}]`
+                        + ` in \`${t.file_path}\` (lines ${t.start_line}–${t.end_line}) · id \`${t.id}\``);
+                }
+                if (note) lines.push('', note);
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            } catch (err) {
+                return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+            }
+        }
+    );
+
+    // ─── explain_symbol ─────────────────────────────────────────────────────────────
+    server.tool(
+        'explain_symbol',
+        'One-call overview of a symbol before you edit it: its signature(s), what it calls (callees), '
+        + 'who calls it (callers / blast radius), subclasses and type users, the HTTP routes it handles, '
+        + 'the tests that exercise it, and git recency/co-change. Composes resolve_symbol + '
+        + 'find_references + find_routes + tests_for + git signals so an agent gets the full context in '
+        + 'a single round-trip instead of four.',
+        {
+            symbol: z.string().describe("Exact symbol name (function, class, interface, method)."),
+            target_class: z.string().optional().describe(
+                "Optional owning class/type to scope the caller/reference dimensions when several symbols share the name."
+            ),
+            response_format: z.enum(['markdown', 'json']).default('markdown').describe(
+                "'markdown' (default) or 'json' (typed { definitions, callees, called_by, subclassed_by, used_as_type_by, routes, tests, recent_changes, co_changes })."
+            ),
+        },
+        async ({ symbol, target_class, response_format }) => {
+            try {
+                const defs = db.resolveSymbol(symbol);
+                if (defs.length === 0) {
+                    const indexEmpty = db.chunkCount() === 0;
+                    const emptyHint = 'Index is empty — run `npm run mcp:index` (or `idx-index --repo <path>`) to build it.';
+                    return response_format === 'json'
+                        ? jsonResult({ symbol, found: false, ...(indexEmpty ? { index_status: 'empty', hint: emptyHint } : {}), definitions: [] })
+                        : { content: [{ type: 'text', text: indexEmpty ? `⚠️ ${emptyHint}` : `Symbol \`${symbol}\` not in index. Try search_code(query="${symbol}").` }] };
+                }
+
+                const { targetDefs, ambiguous, calls, inherits, types, references } =
+                    findReferences(db, symbol, { targetClass: target_class || null });
+                const scipRefs = references || [];
+                const callees = [...new Set(defs.flatMap(d => d.calls || []))].sort();
+                const tests = testsForSymbol(symbol);
+                const defIds = new Set(defs.map(d => d.id));
+                const routes = findRoutes(db, {}).filter(r => r.handler_name === symbol || (r.id && defIds.has(r.id)));
+                const files = [...new Set(targetDefs.map(d => d.file_path))];
+                const coChanges = coChangeFiles(gitSignals, files);
+                const recentChanges = files
+                    .map(f => ({ file: f, hotness: Number(gitBoostScore(gitSignals, f).toFixed(3)) }))
+                    .filter(r => r.hotness > 0)
+                    .sort((a, b) => b.hotness - a.hotness || a.file.localeCompare(b.file));
+                const fresh = indexFreshness();
+                const note = freshnessNote(fresh);
+
+                if (response_format === 'json') {
+                    return jsonResult({
+                        symbol,
+                        target_class: target_class || null,
+                        ambiguous,
+                        definition_count: defs.length,
+                        definitions: defs.map(d => {
+                            const cen = db.getCentrality?.(d.id);
+                            return { ...chunkCard(d), signature: extractSignatureLine(d.code_snippet), ...(cen ? { centrality: cen } : {}) };
+                        }),
+                        callees,
+                        called_by: {
+                            high: calls.high.map(h => refCard({ ...h, confidence: 'high' })),
+                            name_only: calls.nameOnly.map(n => refCard({ ...n, confidence: 'name-only' })),
+                        },
+                        subclassed_by: inherits.map(refCard),
+                        used_as_type_by: types.map(refCard),
+                        referenced_by_resolved: scipRefs.map(refCard),
+                        routes,
+                        tests: tests.map(chunkCard),
+                        recent_changes: recentChanges,
+                        co_changes: coChanges,
+                        index: fresh,
+                    });
+                }
+
+                const callerTotal = calls.high.length + calls.nameOnly.length;
+                const lines = [`# 🔎 \`${target_class ? target_class + '.' : ''}${symbol}\``];
+                if (ambiguous) lines.push(`> ⚠️ ${defs.length} symbols named \`${symbol}\`${target_class ? '' : ' — pass target_class to scope callers/references'}.`);
+                for (const d of defs) {
+                    const cen = db.getCentrality?.(d.id);
+                    const cenTag = cen ? ` · 🎯 centrality #${cen.rank}/${cen.total}${cen.rank <= Math.ceil(cen.total * 0.1) ? ' (hub)' : ''}` : '';
+                    lines.push('', `**${d.class_context ? d.class_context + '.' : ''}${d.name}** [${d.node_type}] · \`${d.file_path}\`:${d.start_line}–${d.end_line} · id \`${d.id}\`${cenTag}`);
+                    lines.push('```', extractSignatureLine(d.code_snippet), '```');
+                }
+                if (callees.length) lines.push('', `**Calls (${callees.length}):** ${callees.slice(0, 20).join(', ')}${callees.length > 20 ? ' …' : ''}`);
+                lines.push('', `**Called by (${callerTotal}):** ${calls.high.length} high-confidence` + (calls.nameOnly.length ? `, ${calls.nameOnly.length} name-only` : ''));
+                for (const h of calls.high.slice(0, 10)) lines.push(`  - ✅ \`${h.chunk.class_context ? h.chunk.class_context + '.' : ''}${h.chunk.name}\` in \`${h.chunk.file_path}\`${h.recvHint ? ` · via ${h.recvHint}` : ''}`);
+                if (inherits.length) lines.push('', `**Subclassed/implemented by (${inherits.length}):** ` + inherits.slice(0, 10).map(r => `\`${r.chunk.name}\``).join(', '));
+                if (types.length) lines.push('', `**Used as a type by (${types.length}):** ` + types.slice(0, 10).map(r => `\`${r.chunk.name}\``).join(', '));
+                if (scipRefs.length) lines.push('', `**🎯 SCIP-resolved references (${scipRefs.length}):** ` + scipRefs.slice(0, 10).map(r => `\`${r.chunk.name}\``).join(', '));
+                if (routes.length) {
+                    lines.push('', `**Routes (${routes.length}):**`);
+                    for (const r of routes) lines.push(`  - **${r.method}** \`${r.path}\``);
+                }
+                lines.push('', tests.length ? `**Tests (${tests.length}):**` : `**Tests:** none found`);
+                for (const t of tests.slice(0, 10)) lines.push(`  - 🧪 \`${t.name}\` in \`${t.file_path}\` · id \`${t.id}\``);
+                if (recentChanges.length) lines.push('', `**Recent activity:** ` + recentChanges.map(r => `\`${r.file}\` (hotness ${r.hotness})`).join(', '));
+                if (coChanges.length) lines.push('', coChangeLine(coChanges));
+                if (note) lines.push('', note);
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            } catch (err) {
+                return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+            }
+        }
+    );
+
+    // ─── impact_of_edit ─────────────────────────────────────────────────────────────
+    server.tool(
+        'impact_of_edit',
+        'The precise BLAST RADIUS of a change before you make it: pass the symbols and/or files '
+        + 'you are about to edit and get the transitively-affected code (callers, subclasses, type '
+        + 'users), the HTTP routes that reach them, the tests to run, and the files that '
+        + 'historically change together. Follows high-confidence edges transitively (precise, no '
+        + 'name collisions); direct ambiguous referrers are listed separately to verify. Most '
+        + 'precise on an index built with --symbol-graph; otherwise resolves at query time.',
+        {
+            symbols: z.array(z.string()).optional().describe('Symbol names about to change (functions, classes, methods).'),
+            files: z.array(z.string()).optional().describe('Repo-relative file paths about to change (every defined symbol in them seeds the impact).'),
+            max_depth: z.number().int().min(1).max(6).default(3).describe('Transitive caller hops to follow (default 3).'),
+            max_nodes: z.number().int().min(1).max(1000).default(200).describe('Cap on affected chunks returned.'),
+            precision: z.enum(['standard', 'strict']).default('standard').describe(
+                "'standard' (default): follow the high-confidence closure (resolved + import/proximity). "
+                + "'strict': follow ONLY provably-unambiguous bindings (sole definition or type-pinned receiver) "
+                + 'for a false-positive-free blast radius — most useful on a --symbol-graph --resolver precise index.'
+            ),
+            response_format: z.enum(['markdown', 'json']).default('markdown').describe(
+                "'markdown' (default) or 'json' (typed { changed, impacted, ambiguous, routes, tests, co_changes })."
+            ),
+        },
+        async ({ symbols = [], files = [], max_depth, max_nodes, precision = 'standard', response_format }) => {
+            try {
+                // Seed: every definition of each symbol + every chunk in each named file.
+                const seedMap = new Map();
+                for (const s of symbols) for (const c of db.resolveSymbol(s)) seedMap.set(c.id, c);
+                for (const f of files) for (const c of db.getChunksByFile(f)) seedMap.set(c.id, c);
+                const seed = [...seedMap.values()];
+
+                if (seed.length === 0) {
+                    const msg = (symbols.length || files.length)
+                        ? `No indexed symbols matched ${JSON.stringify([...symbols, ...files])}. Check the names/paths, or run search_code.`
+                        : 'Pass `symbols` and/or `files` you are about to change.';
+                    return response_format === 'json'
+                        ? jsonResult({ changed: [], impacted: [], ambiguous: [], routes: [], tests: [], co_changes: [], note: msg })
+                        : { content: [{ type: 'text', text: msg }] };
+                }
+
+                const { impacted, ambiguous, truncated, usedGraph } = buildImpact(db, seed, { maxDepth: max_depth, maxNodes: max_nodes, precision });
+
+                // Affected = seed ∪ impacted. Split tests out from production code.
+                const affected = [...seed.map(c => ({ chunk: c, depth: 0, kind: 'seed' })), ...impacted];
+                const affectedIds = new Set(affected.map(a => a.chunk.id));
+                const isTest = (c) => TEST_FILE_RE.test(c.file_path);
+                const impactedCode = impacted.filter(a => !isTest(a.chunk));
+                const tests = affected.filter(a => isTest(a.chunk)).map(a => a.chunk);
+
+                // Routes whose handler chunk is in the affected set.
+                const routes = findRoutes(db, {}).filter(r => r.id && affectedIds.has(r.id));
+                const seedFiles = [...new Set(seed.map(c => c.file_path))];
+                const coChanges = coChangeFiles(gitSignals, seedFiles);
+                const fresh = indexFreshness();
+                const note = freshnessNote(fresh);
+
+                if (response_format === 'json') {
+                    return jsonResult({
+                        seed_symbols: symbols, seed_files: files,
+                        resolution: usedGraph ? 'symbol-graph' : 'query-time',
+                        precision,
+                        changed: seed.map(chunkCard),
+                        impacted: impactedCode.map(a => ({ ...chunkCard(a.chunk), depth: a.depth, via: a.kind })),
+                        ambiguous: ambiguous.map(a => ({ ...chunkCard(a.chunk), via: a.kind })),
+                        routes,
+                        tests: tests.map(chunkCard),
+                        co_changes: coChanges,
+                        truncated,
+                        index: fresh,
+                    });
+                }
+
+                const ref = (c) => `\`${c.class_context ? c.class_context + '.' : ''}${c.name}\` in \`${c.file_path}\`:${c.start_line}`;
+                const lines = [`# 💥 Impact of editing ${seed.map(c => `\`${c.name}\``).slice(0, 8).join(', ')}`];
+                lines.push(`> resolution: ${usedGraph ? 'symbol-graph (precise)' : 'query-time'} · precision: ${precision}${truncated ? ` · ⚠️ truncated at ${max_nodes} nodes` : ''}`);
+                lines.push('', `**Changed (${seed.length}):** ${seed.map(c => `\`${c.name}\``).join(', ')}`);
+                lines.push('', `**Impacted code (${impactedCode.length})** — transitive high-confidence callers/users:`);
+                for (const a of impactedCode.slice(0, 40)) lines.push(`  - [d${a.depth}·${a.kind}] ${ref(a.chunk)}`);
+                if (impactedCode.length > 40) lines.push(`  …and ${impactedCode.length - 40} more`);
+                lines.push('', tests.length ? `**Tests to run (${tests.length}):**` : `**Tests to run:** none found`);
+                for (const t of tests.slice(0, 20)) lines.push(`  - 🧪 ${ref(t)} · id \`${t.id}\``);
+                if (routes.length) {
+                    lines.push('', `**Affected routes (${routes.length}):**`);
+                    for (const r of routes) lines.push(`  - **${r.method}** \`${r.path}\` → \`${r.handler_name}\``);
+                }
+                if (ambiguous.length) {
+                    lines.push('', `**Ambiguous (${ambiguous.length}) — verify (same-named symbol, not expanded):**`);
+                    for (const a of ambiguous.slice(0, 15)) lines.push(`  - ❔ ${ref(a.chunk)}`);
+                }
+                if (coChanges.length) lines.push('', coChangeLine(coChanges));
+                if (!usedGraph) lines.push('', '> ℹ️ Build the index with `--symbol-graph` for a precomputed, chunk-precise blast radius.');
+                if (note) lines.push('', note);
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            } catch (err) {
+                return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+            }
+        }
+    );
+
+    // ─── trace_taint ─────────────────────────────────────────────────────────────────
+    server.tool(
+        'trace_taint',
+        'Security: trace UNTRUSTED data from a source (request body/query/params, argv/env, stdin, '
+        + 'socket/file reads) to a dangerous SINK (eval/exec, SQL, fs/path, HTML, outbound request) '
+        + 'across the call graph — surfacing injection-class risks (rce/sqli/xss/path/ssrf) with the '
+        + 'concrete source→sink path. Same-function flows are high-confidence; cross-function '
+        + 'reachability is medium; a sanitizer on the path lowers it. FINDER, not a verifier — it '
+        + 'misses dynamic dispatch / reflection / ORM indirection, so "no flows" ≠ "safe". '
+        + 'JS/TS + Python. Most precise on a `--symbol-graph` index.',
+        {
+            source_kind: z.string().optional().describe("Restrict to one source kind (e.g. 'http-request', 'process-input', 'stdin')."),
+            category: z.enum(['rce', 'sqli', 'xss', 'path', 'ssrf']).optional().describe('Restrict to one sink category.'),
+            max_depth: z.number().int().min(1).max(8).default(4).describe('Cross-function call hops to follow from a source (default 4).'),
+            max_flows: z.number().int().min(1).max(500).default(100).describe('Cap on flows returned (default 100).'),
+            response_format: z.enum(['markdown', 'json']).default('markdown').describe("'markdown' (default) or 'json' (typed { flows: [{ source, sink, path, via, confidence, sanitized }] })."),
+        },
+        async ({ source_kind, category, max_depth, max_flows, response_format }) => {
+            try {
+                const { flows, truncated, scanned } = traceTaint(db, {
+                    sourceKind: source_kind || null, sinkCategory: category || null, maxDepth: max_depth, maxFlows: max_flows,
+                });
+                if (response_format === 'json') {
+                    return jsonResult({ source_kind: source_kind || null, category: category || null, scanned, flow_count: flows.length, truncated, flows });
+                }
+                const lines = [`# 🧪 Taint flows — ${flows.length}${truncated ? '+' : ''} found (scanned ${scanned} chunks)`, ''];
+                if (!flows.length) lines.push('No source→sink flows matched. ⚠️ This is a finder, not a verifier — absence of a flow is not proof of safety.');
+                for (const f of flows.slice(0, 40)) {
+                    lines.push(`- **${f.sink.category.toUpperCase()}** [${f.confidence}${f.sanitized ? ' · sanitizer on path' : ''}] — \`${f.source.kind}\` → \`${f.sink.label}\``);
+                    lines.push(`  - source \`${f.source.name}\` in \`${f.source.file_path}\`:${f.source.line}`);
+                    lines.push(`  - sink   \`${f.sink.name}\` in \`${f.sink.file_path}\`:${f.sink.line}  (${f.via}, depth ${f.depth})`);
+                }
+                if (flows.length > 40) lines.push(`\n…and ${flows.length - 40} more.`);
+                lines.push('', '> Heuristic finder (JS/TS + Python). Triage each flow against its path; it can over- and under-report.');
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            } catch (err) {
+                return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+            }
+        }
+    );
+
+    // ─── find_tainted_sinks ──────────────────────────────────────────────────────────
+    server.tool(
+        'find_tainted_sinks',
+        'Security orientation: list every dangerous SINK in the codebase (eval/exec, SQL, fs/path, '
+        + 'HTML, outbound requests) grouped by category, each flagged with whether an untrusted '
+        + 'SOURCE reaches it. Use it FIRST to map the attack surface, then trace_taint a specific '
+        + 'one. JS/TS + Python; same heuristic-finder caveats as trace_taint.',
+        {
+            category: z.enum(['rce', 'sqli', 'xss', 'path', 'ssrf']).optional().describe('Restrict to one sink category.'),
+            reachable_only: z.boolean().default(false).describe('Only sinks reachable from an untrusted source.'),
+            max_depth: z.number().int().min(1).max(8).default(4).describe('Reachability hops to consider (default 4).'),
+            response_format: z.enum(['markdown', 'json']).default('markdown').describe("'markdown' (default) or 'json' (typed { sinks_by_category })."),
+        },
+        async ({ category, reachable_only, max_depth, response_format }) => {
+            try {
+                const { byCategory, scanned, flowCount } = findTaintedSinks(db, {
+                    category: category || null, reachableOnly: reachable_only, maxDepth: max_depth,
+                });
+                const total = Object.values(byCategory).reduce((s, a) => s + a.length, 0);
+                if (response_format === 'json') {
+                    return jsonResult({ category: category || null, reachable_only, scanned, sink_count: total, reachable_flow_count: flowCount, sinks_by_category: byCategory });
+                }
+                const lines = [`# 🎯 Dangerous sinks — ${total} (scanned ${scanned} chunks)`, ''];
+                if (!total) lines.push('No sinks matched these filters.');
+                for (const cat of CATEGORY_SEVERITY) {
+                    const list = byCategory[cat];
+                    if (!list || !list.length) continue;
+                    const reached = list.filter(s => s.reached_by_source).length;
+                    lines.push(`## ${cat.toUpperCase()} — ${list.length}${reached ? ` (${reached} reachable from untrusted input ⚠️)` : ''}`);
+                    for (const s of list.slice(0, 25)) {
+                        lines.push(`  - ${s.reached_by_source ? '⚠️ ' : ''}\`${s.label}\` in \`${s.file_path}\`:${s.line} — \`${s.name}\``);
+                    }
+                    if (list.length > 25) lines.push(`  …and ${list.length - 25} more`);
+                    lines.push('');
+                }
+                lines.push('> Heuristic finder (JS/TS + Python). A flagged sink is a place to look, not a confirmed bug.');
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            } catch (err) {
+                return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+            }
+        }
+    );
 }