nodebench-mcp 2.14.1 → 2.15.0

package/dist/__tests__/tools.test.js

@@ -3,7 +3,7 @@
  * Covers: static, unit, integration layers.
  * Live E2E layer is tested via bash pipe in the flywheel step.
  */
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, afterEach } from "vitest";
 import os from "node:os";
 import path from "node:path";
 import { mkdtemp, writeFile } from "node:fs/promises";
@@ -39,7 +39,8 @@ import { patternTools } from "../tools/patternTools.js";
 import { gitWorkflowTools } from "../tools/gitWorkflowTools.js";
 import { seoTools } from "../tools/seoTools.js";
 import { voiceBridgeTools } from "../tools/voiceBridgeTools.js";
-import { getQuickRef, hybridSearch, TOOL_REGISTRY, SEARCH_MODES, ALL_REGISTRY_ENTRIES, WORKFLOW_CHAINS } from "../tools/toolRegistry.js";
+import { critterTools } from "../tools/critterTools.js";
+import { getQuickRef, hybridSearch, TOOL_REGISTRY, SEARCH_MODES, ALL_REGISTRY_ENTRIES, WORKFLOW_CHAINS, tokenize, buildDenseIndex, getToolComplexity } from "../tools/toolRegistry.js";
 // Assemble all tools like index.ts does
 const domainTools = [
     ...verificationTools,
@@ -72,6 +73,7 @@ const domainTools = [
     ...gitWorkflowTools,
     ...seoTools,
     ...voiceBridgeTools,
+    ...critterTools,
 ];
 const metaTools = createMetaTools(domainTools);
 const allToolsWithoutDiscovery = [...domainTools, ...metaTools];
@@ -81,9 +83,9 @@ const allTools = [...allToolsWithoutDiscovery, ...discoveryTools];
 // STATIC LAYER — structure validation
 // ═══════════════════════════════════════════════════════════════════════════
 describe("Static: tool structure", () => {
-    it("should have 162 tools total", () => {
-        // 157 domain tools + 2 meta tools (findTools, getMethodology) + 3 progressive discovery tools
-        expect(allTools.length).toBe(162);
+    it("should have 163 tools total", () => {
+        // 158 domain tools + 2 meta tools (findTools, getMethodology) + 3 progressive discovery tools
+        expect(allTools.length).toBe(163);
     });
     it("every tool has name, description, inputSchema, handler", () => {
         for (const tool of allTools) {
@@ -99,6 +101,18 @@ describe("Static: tool structure", () => {
         const names = allTools.map((t) => t.name);
         expect(new Set(names).size).toBe(names.length);
     });
+    it("every registered tool has MCP annotations (category, phase, complexity)", () => {
+        // MCP 2025-11-25 spec: annotations field provides behavior hints for models.
+        // We surface category, phase, complexity from the registry as annotations.
+        for (const tool of allTools) {
+            const entry = TOOL_REGISTRY.get(tool.name);
+            expect(entry, `Missing registry entry for ${tool.name}`).toBeDefined();
+            expect(entry.category).toBeTruthy();
+            expect(entry.phase).toBeTruthy();
+            const complexity = getToolComplexity(tool.name);
+            expect(["low", "medium", "high"]).toContain(complexity);
+        }
+    });
     it("abandon_cycle tool exists in verificationTools", () => {
         const tool = verificationTools.find((t) => t.name === "abandon_cycle");
         expect(tool).toBeDefined();
@@ -1799,13 +1813,31 @@ describe("Integration: full benchmark lifecycle", () => {
 // ═══════════════════════════════════════════════════════════════════════
 const toolDescs = allTools.map((t) => ({ name: t.name, description: t.description }));
 describe("Search engine: registry coverage", () => {
-    it("should have a registry entry for every tool (162/162)", () => {
+    it("should have a registry entry for every tool (163/163)", () => {
         const missing = allTools.filter((t) => !TOOL_REGISTRY.has(t.name));
         expect(missing.map((t) => t.name)).toEqual([]);
         expect(TOOL_REGISTRY.size).toBe(allTools.length);
     });
-    it("should expose all 7 search modes", () => {
-        expect(SEARCH_MODES).toEqual(["hybrid", "fuzzy", "regex", "prefix", "semantic", "exact", "dense"]);
+    it("should expose all 8 search modes", () => {
+        expect(SEARCH_MODES).toEqual(["hybrid", "fuzzy", "regex", "prefix", "semantic", "exact", "dense", "embedding"]);
+    });
+    it("discover_tools category enum covers every registry category", () => {
+        const discoverTool = allTools.find((t) => t.name === "discover_tools");
+        expect(discoverTool).toBeDefined();
+        const categoryEnum = discoverTool.inputSchema.properties.category.enum;
+        const registryCategories = new Set(ALL_REGISTRY_ENTRIES.map((e) => e.category));
+        for (const cat of registryCategories) {
+            expect(categoryEnum, `category "${cat}" missing from discover_tools enum`).toContain(cat);
+        }
+    });
+    it("get_workflow_chain enum covers every WORKFLOW_CHAINS key", () => {
+        const chainTool = allTools.find((t) => t.name === "get_workflow_chain");
+        expect(chainTool).toBeDefined();
+        const chainEnum = chainTool.inputSchema.properties.chain.enum;
+        for (const key of Object.keys(WORKFLOW_CHAINS)) {
+            expect(chainEnum, `chain "${key}" missing from get_workflow_chain enum`).toContain(key);
+        }
+        expect(chainEnum).toContain("list");
     });
     it("should have quickRef for every registered tool", () => {
         for (const tool of allTools) {
@@ -1943,6 +1975,281 @@ describe("Search engine: bigram phrase matching", () => {
         expect(names.some((n) => n.includes("parallel") || n.includes("agent"))).toBe(true);
     });
 });
+// ── Dense search NDCG regression guard ──────────────────────────────────
+// Tested BM25 vs TF-IDF cosine (v2.14.2): TF-IDF won 0.692 vs 0.691.
+// BM25's length normalization adds no value for short tool descriptions.
+// Keeping TF-IDF cosine. This test guards against ranking regressions.
+describe("Search engine: dense search NDCG@5 regression guard", () => {
+    function ndcg(rankedNames, idealNames, k) {
+        const relevance = new Map();
+        idealNames.forEach((name, i) => relevance.set(name, idealNames.length - i));
+        let dcg = 0;
+        for (let i = 0; i < Math.min(k, rankedNames.length); i++) {
+            const rel = relevance.get(rankedNames[i]) ?? 0;
+            dcg += rel / Math.log2(i + 2);
+        }
+        let idcg = 0;
+        const idealRels = idealNames.map((_, i) => idealNames.length - i).sort((a, b) => b - a);
+        for (let i = 0; i < Math.min(k, idealRels.length); i++) {
+            idcg += idealRels[i] / Math.log2(i + 2);
+        }
+        return idcg === 0 ? 0 : dcg / idcg;
+    }
+    const EVAL_QUERIES = [
+        { query: "verify my implementation", ideal: ["start_verification_cycle", "get_verification_status", "log_test_result", "run_quality_gate", "triple_verify"] },
+        { query: "security audit", ideal: ["scan_dependencies", "run_code_analysis", "scan_terminal_security", "assess_risk", "check_git_compliance"] },
+        { query: "write an academic paper", ideal: ["polish_academic_text", "check_paper_logic", "generate_academic_caption", "review_paper_as_reviewer", "compress_or_expand_text"] },
+        { query: "deploy my changes", ideal: ["run_mandatory_flywheel", "run_quality_gate", "assess_risk", "run_closed_loop", "log_test_result"] },
+        { query: "parallel agent coordination", ideal: ["claim_agent_task", "get_parallel_status", "assign_agent_role", "bootstrap_parallel_agents", "release_agent_task"] },
+        { query: "seo website performance", ideal: ["seo_audit_url", "check_page_performance", "analyze_seo_content", "check_wordpress_site", "scan_wordpress_updates"] },
+        { query: "voice pipeline latency", ideal: ["benchmark_voice_latency", "design_voice_pipeline", "analyze_voice_config", "generate_voice_scaffold"] },
+        { query: "session notes context", ideal: ["save_session_note", "load_session_notes", "refresh_task_context"] },
+        { query: "git compliance merge", ideal: ["check_git_compliance", "enforce_merge_gate", "review_pr_checklist"] },
+        { query: "benchmark autonomous capability", ideal: ["start_autonomy_benchmark", "complete_autonomy_benchmark", "log_benchmark_milestone", "benchmark_models"] },
+        { query: "find tools for testing", ideal: ["discover_tools", "findTools", "log_test_result", "run_tests_cli", "start_eval_run"] },
+        { query: "knowledge learning record", ideal: ["record_learning", "search_all_knowledge", "save_session_note"] },
+    ];
+    it("TF-IDF cosine dense search should maintain NDCG@5 >= 0.60 across eval queries", () => {
+        const { vectors, idf } = buildDenseIndex();
+        const K = 5;
+        let totalNDCG = 0;
+        for (const { query, ideal } of EVAL_QUERIES) {
+            const queryTokens = tokenize(query.toLowerCase());
+            const queryTf = new Map();
+            for (const t of queryTokens)
+                queryTf.set(t, (queryTf.get(t) ?? 0) + 1);
+            const maxFreq = Math.max(...queryTf.values(), 1);
+            for (const [k, v] of queryTf)
+                queryTf.set(k, v / maxFreq);
+            const queryVec = new Map();
+            for (const [term, tfVal] of queryTf) {
+                queryVec.set(term, tfVal * (idf.get(term) ?? 1));
+            }
+            const scores = [];
+            for (const [name, docVec] of vectors) {
+                let dot = 0, normA = 0, normB = 0;
+                for (const [k, v] of queryVec) {
+                    normA += v * v;
+                    const bv = docVec.get(k);
+                    if (bv !== undefined)
+                        dot += v * bv;
+                }
+                for (const v of docVec.values())
+                    normB += v * v;
+                const sim = (normA === 0 || normB === 0) ? 0 : dot / (Math.sqrt(normA) * Math.sqrt(normB));
+                if (sim > 0)
+                    scores.push({ name, sim });
+            }
+            scores.sort((a, b) => b.sim - a.sim);
+            const rankedNames = scores.slice(0, K).map(r => r.name);
+            totalNDCG += ndcg(rankedNames, ideal, K);
+        }
+        const avgNDCG = totalNDCG / EVAL_QUERIES.length;
+        expect(avgNDCG).toBeGreaterThanOrEqual(0.60);
+    });
+});
+// ── FTS5+BM25 A/B test: search_all_knowledge (recon_findings + gaps) ────
+// Verifies that FTS5 BM25 ranking produces relevance-ordered results
+// for variable-length recon findings and gaps, compared to LIKE (recency-only).
+describe("FTS5 BM25: search_all_knowledge relevance ranking", () => {
+    const searchTool = reconTools.find((t) => t.name === "search_all_knowledge");
+    const logFinding = reconTools.find((t) => t.name === "log_recon_finding");
+    const runRecon = reconTools.find((t) => t.name === "run_recon");
+    const startCycle = verificationTools.find((t) => t.name === "start_verification_cycle");
+    const logGap = verificationTools.find((t) => t.name === "log_gap");
+    it("should rank recon findings by BM25 relevance (term-specific > generic mentions)", async () => {
+        // Setup: create a recon session with varied findings
+        const session = (await runRecon.handler({ target: "BM25 FTS5 test session" }));
+        const sid = session.sessionId;
+        // Insert findings — the "MCP SDK breaking change" finding is highly relevant
+        await logFinding.handler({
+            sessionId: sid,
+            category: "breaking_change",
+            summary: "MCP SDK v2.0 introduces breaking changes to the transport layer requiring migration",
+            relevance: "All MCP servers must update their transport initialization code",
+            actionItems: "Update transport from stdio to new StreamableHTTP pattern",
+        });
+        await logFinding.handler({
+            sessionId: sid,
+            category: "best_practice",
+            summary: "React 19 compiler optimizations reduce bundle size by 15%",
+            relevance: "Frontend build pipeline could benefit from upgrade",
+            actionItems: "Evaluate React 19 migration path",
+        });
+        await logFinding.handler({
+            sessionId: sid,
+            category: "new_feature",
+            summary: "New MCP SDK sampling API enables server-initiated LLM requests",
+            relevance: "MCP servers can now call LLMs directly through the protocol",
+            actionItems: "Integrate sampling API into MCP tool handlers",
+        });
+        // Query for "MCP SDK breaking" — should rank MCP findings above React
+        const result = (await searchTool.handler({ query: "MCP SDK breaking" }));
+        const findings = result.reconFindings;
+        // At minimum, MCP-related findings should appear (FTS5 MATCH or LIKE fallback)
+        expect(findings.length).toBeGreaterThan(0);
+        // If FTS5 BM25 is working, the breaking_change finding should rank first
+        // (it has the most term overlap with "MCP SDK breaking")
+        if (findings.length >= 2) {
+            const firstSummary = findings[0].summary.toLowerCase();
+            expect(firstSummary).toContain("breaking");
+        }
+    });
+    it("should rank gaps by BM25 relevance (specific match > loose mention)", async () => {
+        // Setup: create a verification cycle with varied gaps
+        const cycle = (await startCycle.handler({
+            title: "BM25 gaps FTS5 test cycle",
+        }));
+        const cid = cycle.cycleId;
+        await logGap.handler({
+            cycleId: cid,
+            severity: "HIGH",
+            title: "SQLite WAL mode lock contention under parallel writes",
+            description: "When multiple agents write to SQLite simultaneously, WAL mode lock contention causes timeout errors after 5 seconds",
+            fixStrategy: "Implement write queue with retry backoff for SQLite parallel access",
+        });
+        await logGap.handler({
+            cycleId: cid,
+            severity: "MEDIUM",
+            title: "API rate limiting not implemented",
+            description: "External API calls have no rate limiting or retry logic",
+            fixStrategy: "Add exponential backoff with jitter for API calls",
+        });
+        await logGap.handler({
+            cycleId: cid,
+            severity: "LOW",
+            title: "Test coverage below 80% for SQLite module",
+            description: "SQLite database module has only 60% test coverage, missing edge cases for concurrent access",
+            fixStrategy: "Add integration tests for SQLite concurrent write scenarios",
+        });
+        // Query for "SQLite parallel" — should rank SQLite-specific gaps above API gap
+        const result = (await searchTool.handler({ query: "SQLite parallel" }));
+        const gaps = result.gaps;
+        expect(gaps.length).toBeGreaterThan(0);
+        // If FTS5 BM25 is working, the WAL lock contention gap (HIGH severity, most term overlap) ranks first
+        if (gaps.length >= 2) {
+            const firstTitle = gaps[0].title.toLowerCase();
+            expect(firstTitle).toContain("sqlite");
+        }
+    });
+});
+// ── Gateway BM25 meta-tool A/B test ────────────────────────────────────
+// Tests BM25 scoring in the gateway metaTools findTools — verifies that
+// IDF-weighted scoring ranks specific tools higher than generic matches.
+describe("Gateway BM25: findTools IDF-weighted ranking", () => {
+    // Simulate the gateway's BM25 scorer with inline implementation
+    function tokenize(text) {
+        return text.toLowerCase().match(/[a-z_]+/g) ?? [];
+    }
+    // Word-count baseline (old approach)
+    function wordCountSearch(query, tools) {
+        const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+        return tools
+            .map((t) => {
+            const text = `${t.name} ${t.description}`.toLowerCase();
+            const hits = words.filter((w) => text.includes(w)).length;
+            return { name: t.name, hits };
+        })
+            .filter((t) => t.hits > 0)
+            .sort((a, b) => b.hits - a.hits)
+            .map((t) => t.name);
+    }
+    // BM25 search (new approach)
+    function bm25Search(query, tools) {
+        const corpus = new Map();
+        for (const t of tools) {
+            corpus.set(t.name, tokenize(`${t.name} ${t.description}`));
+        }
+        let totalLen = 0;
+        for (const tokens of corpus.values())
+            totalLen += tokens.length;
+        const avgDl = corpus.size > 0 ? totalLen / corpus.size : 1;
+        const docFreq = new Map();
+        for (const tokens of corpus.values()) {
+            const unique = new Set(tokens);
+            for (const t of unique)
+                docFreq.set(t, (docFreq.get(t) ?? 0) + 1);
+        }
+        const N = corpus.size;
+        const idf = new Map();
+        for (const [term, df] of docFreq) {
+            idf.set(term, Math.log((N - df + 0.5) / (df + 0.5) + 1));
+        }
+        const queryTokens = tokenize(query);
+        const k1 = 1.2, b = 0.75;
+        return tools
+            .map((t) => {
+            const docTokens = corpus.get(t.name) ?? [];
+            const dl = docTokens.length;
+            const tf = new Map();
+            for (const tok of docTokens)
+                tf.set(tok, (tf.get(tok) ?? 0) + 1);
+            let score = 0;
+            for (const qt of queryTokens) {
+                const termTf = tf.get(qt) ?? 0;
+                if (termTf === 0)
+                    continue;
+                const termIdf = idf.get(qt) ?? 0;
+                score += termIdf * (termTf * (k1 + 1)) / (termTf + k1 * (1 - b + b * (dl / avgDl)));
+            }
+            return { name: t.name, score };
+        })
+            .filter((t) => t.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .map((t) => t.name);
+    }
+    // Use the real tool list from allTools
+    const toolEntries = allTools.map((t) => ({ name: t.name, description: t.description }));
+    // Queries where IDF matters — rare terms should beat common ones
+    const IDF_QUERIES = [
+        {
+            query: "flicker detection android",
+            mustRankHigher: "start_flicker_analysis",
+            mustRankLower: "web_search",
+            reason: "'flicker' is rare (high IDF), 'search' is common (low IDF)",
+        },
+        {
+            query: "autonomous benchmark c compiler",
+            mustRankHigher: "start_autonomy_benchmark",
+            mustRankLower: "run_quality_gate",
+            reason: "'autonomy' and 'benchmark' are specific (high IDF)",
+        },
+        {
+            query: "toon encode token",
+            mustRankHigher: "toon_encode",
+            mustRankLower: "record_learning",
+            reason: "'toon' is extremely rare (high IDF), should dominate scoring",
+        },
+    ];
+    it("BM25 should outperform word-count on IDF-sensitive queries", () => {
+        let bm25Wins = 0;
+        let wordCountWins = 0;
+        for (const { query, mustRankHigher, mustRankLower } of IDF_QUERIES) {
+            const bm25Results = bm25Search(query, toolEntries);
+            const wordResults = wordCountSearch(query, toolEntries);
+            const bm25IdxHigh = bm25Results.indexOf(mustRankHigher);
+            const bm25IdxLow = bm25Results.indexOf(mustRankLower);
+            const wordIdxHigh = wordResults.indexOf(mustRankHigher);
+            const wordIdxLow = wordResults.indexOf(mustRankLower);
+            // BM25 correctly ranks the specific tool higher
+            if (bm25IdxHigh !== -1 && (bm25IdxLow === -1 || bm25IdxHigh < bm25IdxLow))
+                bm25Wins++;
+            if (wordIdxHigh !== -1 && (wordIdxLow === -1 || wordIdxHigh < wordIdxLow))
+                wordCountWins++;
+        }
+        // BM25 should win at least as many IDF-sensitive queries as word-count
+        expect(bm25Wins).toBeGreaterThanOrEqual(wordCountWins);
+        // BM25 should get at least 2 of 3 IDF-sensitive queries correct
+        expect(bm25Wins).toBeGreaterThanOrEqual(2);
+    });
+    it("BM25 should return results for all eval queries (no regressions)", () => {
+        const queries = ["verify implementation", "search the web", "create document", "find stock prices", "security audit"];
+        for (const q of queries) {
+            const results = bm25Search(q, toolEntries);
+            expect(results.length).toBeGreaterThan(0);
+        }
+    });
+});
 // ── Contract Compliance Tool Tests ──────────────────────────────────────
 describe("check_contract_compliance", () => {
     it("should return N/A score when no tool call data exists", async () => {
@@ -2180,4 +2487,699 @@ describe("Workflow chains: ablation_eval and task_bank_setup", () => {
         expect(WORKFLOW_CHAINS.task_bank_setup.steps.length).toBe(9);
     });
 });
+// ── Embedding search A/B: natural language queries where synonym map misses ──
+// ═══════════════════════════════════════════════════════════════════════════
+// CRITTER TOOL — intentionality check
+// ═══════════════════════════════════════════════════════════════════════════
+describe("Unit: critter_check", () => {
+    const tool = critterTools.find((t) => t.name === "critter_check");
+    it("scores a well-intentioned task as proceed", async () => {
+        const result = await tool.handler({
+            task: "Add embedding-based semantic search to discover_tools",
+            why: "Natural language queries like 'keep track of what I learned' miss record_learning because lexical search can't bridge vocabulary gaps",
+            who: "AI agents using the MCP server who think in natural language, not tool names",
+            success_looks_like: "A/B eval shows 60% lexical → 85%+ hybrid hit rate with zero drops",
+        });
+        expect(result.score).toBeGreaterThanOrEqual(70);
+        expect(result.verdict).toBe("proceed");
+    });
+    it("catches circular reasoning and vague audience", async () => {
+        const result = await tool.handler({
+            task: "Add user authentication and login system to the application",
+            why: "Because we need user authentication and login system in the application",
+            who: "users",
+        });
+        // Circular (-30) + vague audience (-20) = 50, well under 70
+        expect(result.score).toBeLessThan(70);
+        expect(result.feedback.some((f) => f.toLowerCase().includes("circular") || f.toLowerCase().includes("vague"))).toBe(true);
+    });
+    it("catches deference over understanding", async () => {
+        const result = await tool.handler({
+            task: "Refactor the database layer",
+            why: "I was told to refactor it in the ticket",
+            who: "Backend developers maintaining the codebase",
+        });
+        expect(result.feedback.some((f) => f.toLowerCase().includes("deference") || f.toLowerCase().includes("authority"))).toBe(true);
+    });
+    it("rewards specificity bonuses", async () => {
+        const result = await tool.handler({
+            task: "Migrate from REST to GraphQL",
+            why: "Our mobile app makes 12 API calls per screen load because REST endpoints return fixed shapes — GraphQL lets us fetch exactly what each screen needs in one round trip",
+            who: "Mobile team (3 iOS + 2 Android devs) who spend 40% of sprint time on API pagination workarounds",
+            success_looks_like: "Screen load API calls drop from 12 to 1-2, mobile team velocity increases by at least 20%",
+            simplest_version: "Start with the 3 highest-traffic screens, keep REST endpoints alive for backwards compat",
+        });
+        expect(result.score).toBeGreaterThanOrEqual(90);
+        expect(result.verdict).toBe("proceed");
+    });
+    it("persists the check to SQLite", async () => {
+        const result = await tool.handler({
+            task: "Test persistence",
+            why: "Verifying that critter checks are saved for accountability",
+            who: "The test suite validating the critter tool",
+        });
+        expect(result.id).toBeDefined();
+        expect(result.id).toMatch(/^crit_/);
+    });
+});
+// These tests verify that when a neural embedding provider IS available,
+// natural language queries that lexical search struggles with get boosted.
+// When no provider is available, they gracefully skip.
+import { _setIndexForTesting, _resetForTesting as resetEmbedding } from "../tools/embeddingProvider.js";
+import { _resetCooccurrenceCache, _setCooccurrenceForTesting, _setWrrfParamsForTesting, _resetWrrfParamsForTesting } from "../tools/toolRegistry.js";
+describe("Embedding search: RRF integration with hybridSearch", () => {
+    it("hybridSearch accepts embeddingQueryVec option without error", () => {
+        // Even without an embedding index loaded, hybridSearch should not throw
+        const results = hybridSearch("verify code", toolDescs, {
+            mode: "hybrid",
+            limit: 5,
+            embeddingQueryVec: new Float32Array([0.5, 0.3, 0.1]),
+        });
+        // Should still return results from lexical strategies
+        expect(results.length).toBeGreaterThan(0);
+    });
+    it("embedding mode without index has no embedding reasons", () => {
+        resetEmbedding();
+        const results = hybridSearch("keep track of lessons", toolDescs, {
+            mode: "embedding",
+            limit: 5,
+            explain: true,
+        });
+        // Without an embedding index, no results should have embedding reasons
+        for (const r of results) {
+            expect(r.matchReasons.some((m) => m.startsWith("embedding:"))).toBe(false);
+        }
+    });
+    it("embedding RRF adds score when index is loaded with mock vectors", () => {
+        // Build a simple mock index: record_learning gets a vector close to the query
+        const mockEntries = toolDescs.map((t) => ({
+            name: t.name,
+            // Give record_learning a "close" vector, everything else a distant one
+            vector: t.name === "record_learning"
+                ? new Float32Array([0.9, 0.1, 0.0])
+                : new Float32Array([0.1, 0.1, 0.9]),
+            nodeType: "tool",
+        }));
+        _setIndexForTesting(mockEntries);
+        const queryVec = new Float32Array([1.0, 0.0, 0.0]);
+        const results = hybridSearch("remember what I learned", toolDescs, {
+            mode: "hybrid",
+            limit: 10,
+            explain: true,
+            embeddingQueryVec: queryVec,
+        });
+        // record_learning should appear and have an embedding:tool_rrf reason
+        const recordLearning = results.find((r) => r.name === "record_learning");
+        expect(recordLearning).toBeDefined();
+        expect(recordLearning.matchReasons.some((r) => r.startsWith("embedding:tool_rrf"))).toBe(true);
+        // Clean up
+        resetEmbedding();
+    });
+    it("embedding-only mode with mock index ranks by RRF", () => {
+        // Set up mock where start_verification_cycle is closest to query
+        const mockEntries = toolDescs.map((t) => ({
+            name: t.name,
+            vector: t.name === "start_verification_cycle"
+                ? new Float32Array([0.95, 0.05, 0.0])
+                : t.name === "run_quality_gate"
+                    ? new Float32Array([0.7, 0.3, 0.0])
+                    : new Float32Array([0.05, 0.05, 0.9]),
+            nodeType: "tool",
+        }));
+        _setIndexForTesting(mockEntries);
+        const queryVec = new Float32Array([1.0, 0.0, 0.0]);
+        const results = hybridSearch("ensure correctness", toolDescs, {
+            mode: "embedding",
+            limit: 5,
+            explain: true,
+            embeddingQueryVec: queryVec,
+        });
+        // In embedding-only mode, results should come from embedding RRF only
+        expect(results.length).toBeGreaterThan(0);
+        expect(results[0].name).toBe("start_verification_cycle");
+        expect(results[0].matchReasons.some((r) => r.startsWith("embedding:tool_rrf"))).toBe(true);
+        resetEmbedding();
+    });
+});
+// ── Agent-as-a-Graph: structural property tests ──────────────────────────
+// These tests verify the STRUCTURAL properties of the bipartite graph search:
+// 1. Domain-only proximity lifts siblings (upward traversal)
+// 2. Type-specific wRRF weight asymmetry (α_D=1.5 > α_T=1.0, per paper + ablation)
+// 3. Strong lexical matches survive noisy embeddings (non-regression)
+// 4. Execution trace edges boost co-occurring tools
+//
+// Unlike tautological tests that mock the "right answer" as close, these tests
+// prove the ALGORITHM works by testing its structural invariants.
+describe("Agent-as-a-Graph: bipartite wRRF structural properties", () => {
+    // Helper: build a bipartite index where specific domains are close but NO tools are
+    function buildDomainOnlyIndex(closeDomains) {
+        const categories = new Set(ALL_REGISTRY_ENTRIES.map((e) => e.category));
+        // ALL tool nodes are distant from query — no direct tool match
+        const toolEntries = toolDescs.map((t) => ({
+            name: t.name,
+            vector: new Float32Array([0.1, 0.1, 0.8]),
+            nodeType: "tool",
+        }));
+        // Only specified domains are close to query
+        const domainEntries = [...categories].map((cat) => ({
+            name: `domain:${cat}`,
+            vector: closeDomains.has(cat)
+                ? new Float32Array([0.85, 0.15, 0.0])
+                : new Float32Array([0.05, 0.05, 0.9]),
+            nodeType: "domain",
+        }));
+        return [...toolEntries, ...domainEntries];
+    }
+    afterEach(() => {
+        resetEmbedding();
+        _resetCooccurrenceCache();
+    });
+    it("domain-only embedding proximity causes measurable rank lift for sibling tools", () => {
+        // Prove CAUSATION, not just presence: compare ranks WITH vs WITHOUT domain proximity.
+        // Use a query that gives moderate lexical scores to research_writing tools,
+        // then show domain_rrf lifts them higher.
+        const query = "polish text for submission";
+        // Step 1: Baseline — lexical only (no embeddings)
+        resetEmbedding();
+        const baseline = hybridSearch(query, toolDescs, {
+            mode: "hybrid",
+            limit: 30,
+            explain: true,
+        });
+        // Find a research_writing tool in baseline and record its rank
+        const rwToolBaseline = baseline.findIndex((r) => r.category === "research_writing");
+        // It should exist somewhere (polish/text/submission have some keyword overlap)
+        expect(rwToolBaseline).toBeGreaterThanOrEqual(0);
+        const rwToolName = baseline[rwToolBaseline].name;
+        const rwBaselineScore = baseline[rwToolBaseline].score;
+        // Step 2: With domain-only embeddings (research_writing domain close, NO tools close)
+        const mockIndex = buildDomainOnlyIndex(new Set(["research_writing"]));
+        _setIndexForTesting(mockIndex);
+        const queryVec = new Float32Array([1.0, 0.0, 0.0]);
+        const enhanced = hybridSearch(query, toolDescs, {
+            mode: "hybrid",
+            limit: 30,
+            explain: true,
+            embeddingQueryVec: queryVec,
+        });
+        const rwToolEnhanced = enhanced.find((r) => r.name === rwToolName);
+        expect(rwToolEnhanced).toBeDefined();
+        // CAUSATION: score increased due to domain_rrf
+        expect(rwToolEnhanced.score).toBeGreaterThan(rwBaselineScore);
+        expect(rwToolEnhanced.matchReasons.some((r) => r.includes("domain_rrf"))).toBe(true);
+        // No tool_rrf (all tools are equally distant)
+        expect(rwToolEnhanced.matchReasons.some((r) => r.includes("tool_rrf"))).toBe(false);
+        // Rank should improve (lower index = higher rank)
+        const rwEnhancedIdx = enhanced.findIndex((r) => r.name === rwToolName);
+        expect(rwEnhancedIdx).toBeLessThanOrEqual(rwToolBaseline);
+    });
+    it("multiple close domains each lift their own sibling tools independently", () => {
+        // Setup: security AND vision domains close, but no tools close
+        const mockIndex = buildDomainOnlyIndex(new Set(["security", "vision"]));
+        _setIndexForTesting(mockIndex);
+        const queryVec = new Float32Array([1.0, 0.0, 0.0]);
+        const results = hybridSearch("analyze security visual", toolDescs, {
+            mode: "embedding",
+            limit: 30,
+            explain: true,
+            embeddingQueryVec: queryVec,
+        });
+        const securityTools = results.filter((r) => r.category === "security" && r.matchReasons.some((mr) => mr.includes("domain_rrf(security")));
+        const visionTools = results.filter((r) => r.category === "vision" && r.matchReasons.some((mr) => mr.includes("domain_rrf(vision")));
+        // Both categories should have siblings lifted
+        expect(securityTools.length).toBeGreaterThanOrEqual(1);
+        expect(visionTools.length).toBeGreaterThanOrEqual(1);
+    });
+    it("type-specific wRRF: domain_rrf score exceeds tool_rrf (paper calibration α_D=1.5 > α_T=1.0)", () => {
+        // After ablation (see "wRRF α ratio ablation" test), paper's domain emphasis wins.
+        // At rank 1: α_D * 1000/(K+1) = 1.5 * 1000/61 ≈ 25, α_T * 1000/(K+1) = 1.0 * 1000/61 ≈ 16.
+        // Domain emphasis means category-level matches contribute MORE than individual tool matches,
+        // which helps surface all tools in a matching domain (upward traversal).
+        const categories = new Set(ALL_REGISTRY_ENTRIES.map((e) => e.category));
+        const targetTool = "polish_academic_text";
+        const toolEntries = toolDescs.map((t) => ({
+            name: t.name,
+            vector: t.name === targetTool
+                ? new Float32Array([0.95, 0.05, 0.0])
+                : new Float32Array([0.1, 0.1, 0.8]),
+            nodeType: "tool",
+        }));
+        const domainEntries = [...categories].map((cat) => ({
+            name: `domain:${cat}`,
+            vector: cat === "research_writing"
+                ? new Float32Array([0.90, 0.10, 0.0])
+                : new Float32Array([0.05, 0.05, 0.9]),
+            nodeType: "domain",
+        }));
+        _setIndexForTesting([...toolEntries, ...domainEntries]);
+        const queryVec = new Float32Array([1.0, 0.0, 0.0]);
+        const results = hybridSearch("academic writing", toolDescs, {
+            mode: "embedding",
+            limit: 20,
+            explain: true,
+            embeddingQueryVec: queryVec,
+        });
+        const target = results.find((r) => r.name === targetTool);
+        expect(target).toBeDefined();
+        // Extract individual RRF scores from matchReasons
+        const toolRrfReason = target.matchReasons.find((r) => r.startsWith("embedding:tool_rrf"));
+        const domainRrfReason = target.matchReasons.find((r) => r.startsWith("embedding:domain_rrf"));
+        expect(toolRrfReason).toBeDefined();
+        expect(domainRrfReason).toBeDefined();
+        const toolScore = parseInt(toolRrfReason.match(/\+(\d+)/)?.[1] ?? "0");
+        const domainScore = parseInt(domainRrfReason.match(/\+(\d+)/)?.[1] ?? "0");
+        // α_D=1.5 > α_T=1.0 → domain_rrf contributes more than tool_rrf at similar ranks
+        expect(domainScore).toBeGreaterThan(toolScore);
+    });
+    it("strong lexical matches are not displaced by noisy embeddings", () => {
+        // "start verification cycle" should easily find start_verification_cycle lexically.
+        // Adding uniformly noisy embeddings should NOT knock it from #1.
+        resetEmbedding();
+        const lexicalResults = hybridSearch("start verification cycle", toolDescs, {
+            mode: "hybrid",
+            limit: 5,
+        });
+        expect(lexicalResults[0].name).toBe("start_verification_cycle");
+        // Add noisy embeddings — all vectors point roughly the same direction
+        const categories = new Set(ALL_REGISTRY_ENTRIES.map((e) => e.category));
+        const toolEntries = toolDescs.map((t, i) => ({
+            name: t.name,
+            vector: new Float32Array([0.2 + (i % 10) * 0.01, 0.3, 0.7]),
+            nodeType: "tool",
+        }));
+        const domainEntries = [...categories].map((cat, i) => ({
+            name: `domain:${cat}`,
+            vector: new Float32Array([0.15 + i * 0.02, 0.25, 0.7]),
+            nodeType: "domain",
+        }));
+        _setIndexForTesting([...toolEntries, ...domainEntries]);
+        const queryVec = new Float32Array([1.0, 0.0, 0.0]);
+        const graphResults = hybridSearch("start verification cycle", toolDescs, {
+            mode: "hybrid",
+            limit: 5,
+            embeddingQueryVec: queryVec,
+        });
+        // Lexical dominance should preserve #1 position
+        expect(graphResults[0].name).toBe("start_verification_cycle");
+    });
+});
+// ── Agent-as-a-Graph: execution trace edge tests ──────────────────────────
+// Validates that co-occurrence edges mined from tool_call_log boost results.
+// Uses _setCooccurrenceForTesting to inject deterministic edges.
+//
+// Key insight: trace edges only boost tools that ALREADY scored > 0 from
+// lexical matching. They lift borderline tools, not create results from nothing.
+// Tests use a data-driven approach: run baseline first, then inject edges
+// targeting actual result entries.
+describe("Agent-as-a-Graph: execution trace edges", () => {
+    const TRACE_QUERY = "verify test quality";
+    afterEach(() => {
+        resetEmbedding();
+        _resetCooccurrenceCache();
+    });
+    it("co-occurrence edges boost a non-top-5 tool by exactly +4", () => {
+        // Step 1: Get natural ranking without trace edges
+        _setCooccurrenceForTesting(new Map());
+        const baseline = hybridSearch(TRACE_QUERY, toolDescs, {
+            mode: "hybrid",
+            limit: 15,
+            explain: true,
+        });
+        expect(baseline.length).toBeGreaterThanOrEqual(6);
+        const topTool = baseline[0].name;
+        const boostTarget = baseline[5].name; // position 6 — NOT in top 5
+        const baselineScore = baseline[5].score;
+        // Step 2: Inject trace edge from top tool → boost target
+        _resetCooccurrenceCache();
+        const edges = new Map();
+        edges.set(topTool, [boostTarget]);
+        _setCooccurrenceForTesting(edges);
+        const boosted = hybridSearch(TRACE_QUERY, toolDescs, {
+            mode: "hybrid",
+            limit: 15,
+            explain: true,
+        });
+        const result = boosted.find((r) => r.name === boostTarget);
+        expect(result).toBeDefined();
+        expect(result.score).toBe(baselineScore + 4);
+        expect(result.matchReasons.some((r) => r === "trace_edge:+4")).toBe(true);
+    });
+    it("top-5 tools do NOT receive trace edge self-boost", () => {
+        // Get natural ranking
+        _setCooccurrenceForTesting(new Map());
+        const baseline = hybridSearch(TRACE_QUERY, toolDescs, {
+            mode: "hybrid",
+            limit: 15,
+            explain: true,
+        });
+        const topTool = baseline[0].name;
+        const topScore = baseline[0].score;
+        const secondTool = baseline[1].name;
+        // Set edge FROM secondTool TO topTool — topTool is already top-5
+        _resetCooccurrenceCache();
+        const edges = new Map();
+        edges.set(secondTool, [topTool]);
+        _setCooccurrenceForTesting(edges);
+        const results = hybridSearch(TRACE_QUERY, toolDescs, {
+            mode: "hybrid",
+            limit: 15,
+            explain: true,
+        });
+        const top = results.find((r) => r.name === topTool);
+        expect(top).toBeDefined();
+        // Score should NOT increase — top-5 tools are excluded from trace boost
+        expect(top.score).toBe(topScore);
+        expect(top.matchReasons.some((r) => r === "trace_edge:+4")).toBe(false);
+    });
+    it("empty co-occurrence map produces no trace_edge boosts", () => {
+        _setCooccurrenceForTesting(new Map());
+        const results = hybridSearch(TRACE_QUERY, toolDescs, {
+            mode: "hybrid",
+            limit: 15,
+            explain: true,
+        });
+        for (const r of results) {
+            expect(r.matchReasons.some((mr) => mr.includes("trace_edge"))).toBe(false);
+        }
+    });
+    it("trace edges from multiple top tools merge — both targets get +4", () => {
+        // Get natural ranking
+        _setCooccurrenceForTesting(new Map());
+        const baseline = hybridSearch(TRACE_QUERY, toolDescs, {
+            mode: "hybrid",
+            limit: 15,
+            explain: true,
+        });
+        expect(baseline.length).toBeGreaterThanOrEqual(8);
+        const topTool1 = baseline[0].name;
+        const topTool2 = baseline[1].name;
+        const target1 = baseline[6].name;
+        const target2 = baseline[7].name;
+        const target1BaseScore = baseline[6].score;
+        const target2BaseScore = baseline[7].score;
+        // Two top tools each point to a different target
+        _resetCooccurrenceCache();
+        const edges = new Map();
+        edges.set(topTool1, [target1]);
+        edges.set(topTool2, [target2]);
+        _setCooccurrenceForTesting(edges);
+        const results = hybridSearch(TRACE_QUERY, toolDescs, {
+            mode: "hybrid",
+            limit: 15,
+            explain: true,
+        });
+        const boosted1 = results.find((r) => r.name === target1);
+        const boosted2 = results.find((r) => r.name === target2);
+        expect(boosted1).toBeDefined();
+        expect(boosted2).toBeDefined();
+        expect(boosted1.score).toBe(target1BaseScore + 4);
+        expect(boosted2.score).toBe(target2BaseScore + 4);
+        expect(boosted1.matchReasons.some((r) => r === "trace_edge:+4")).toBe(true);
+        expect(boosted2.matchReasons.some((r) => r === "trace_edge:+4")).toBe(true);
+    });
+});
+// ── Industry-Standard IR Metrics: Recall@K, mAP@K, NDCG@K ──────────────
+// Every tool retrieval paper (ToolBench, AnyTool, Agent-as-a-Graph, TOOLRET)
+// reports these metrics. We evaluate hybrid search against 15 intent-based
+// queries with ground-truth relevant tool sets.
+//
+// Standards compared against:
+// - Agent-as-a-Graph (arxiv:2511.18194): Recall@5=0.85, NDCG@5=0.47
+// - TOOLRET (ACL 2025): best NDCG@10=33.83 (bi-encoder only)
+// - ToolBench: NDCG@5=84.9 (contrastive-trained Sentence-BERT)
+//
+// Our system is different (single MCP server, 163 tools, 14-strategy ensemble)
+// so absolute numbers aren't comparable, but we should track and not regress.
+describe("Industry-standard IR metrics: Recall@K, mAP@K, NDCG@K", () => {
+    // Ground truth: query → set of relevant tools (any order).
+    // Each query has 3-6 relevant tools, reflecting realistic intent breadth.
+    const EVAL_QUERIES = [
+        { query: "verify my implementation is correct", relevant: ["start_verification_cycle", "get_verification_status", "log_test_result", "run_quality_gate", "triple_verify"] },
+        { query: "search past findings and lessons", relevant: ["search_all_knowledge", "record_learning", "load_session_notes"] },
+        { query: "run security audit on codebase", relevant: ["scan_dependencies", "run_code_analysis", "scan_terminal_security", "assess_risk"] },
+        { query: "write and polish academic paper", relevant: ["polish_academic_text", "check_paper_logic", "generate_academic_caption", "review_paper_as_reviewer"] },
+        { query: "coordinate parallel agent tasks", relevant: ["claim_agent_task", "get_parallel_status", "assign_agent_role", "bootstrap_parallel_agents", "release_agent_task"] },
+        { query: "check website performance and SEO", relevant: ["seo_audit_url", "check_page_performance", "analyze_seo_content"] },
+        { query: "save and recall context between sessions", relevant: ["save_session_note", "load_session_notes", "refresh_task_context"] },
+        { query: "review git compliance before merge", relevant: ["check_git_compliance", "enforce_merge_gate", "review_pr_checklist"] },
+        { query: "benchmark model autonomy", relevant: ["start_autonomy_benchmark", "complete_autonomy_benchmark", "log_benchmark_milestone"] },
+        { query: "capture screenshot of UI state", relevant: ["capture_screenshot", "capture_full_page", "compare_screenshots"] },
+        { query: "encode data in compact token format", relevant: ["toon_encode", "toon_decode"] },
+        { query: "mine patterns from past sessions", relevant: ["mine_session_patterns", "predict_risks_from_patterns"] },
+        { query: "detect video flicker artifacts", relevant: ["analyze_video_flicker", "compare_video_segments", "get_flicker_report"] },
+        { query: "design voice interaction pipeline", relevant: ["design_voice_pipeline", "analyze_voice_config", "generate_voice_scaffold", "benchmark_voice_latency"] },
+        { query: "check if this task is worth doing", relevant: ["critter_check"] },
+    ];
+    function recallAtK(ranked, relevant, k) {
+        const topK = ranked.slice(0, k);
+        const found = topK.filter((name) => relevant.has(name)).length;
+        return found / relevant.size;
+    }
+    function averagePrecisionAtK(ranked, relevant, k) {
+        let hits = 0;
+        let sumPrecision = 0;
+        for (let i = 0; i < Math.min(k, ranked.length); i++) {
+            if (relevant.has(ranked[i])) {
+                hits++;
+                sumPrecision += hits / (i + 1);
+            }
+        }
+        return relevant.size === 0 ? 0 : sumPrecision / relevant.size;
+    }
+    function ndcgAtK(ranked, relevant, k) {
+        // Binary relevance: 1 if relevant, 0 otherwise
+        let dcg = 0;
+        for (let i = 0; i < Math.min(k, ranked.length); i++) {
+            if (relevant.has(ranked[i]))
+                dcg += 1 / Math.log2(i + 2);
+        }
+        let idcg = 0;
+        const idealCount = Math.min(k, relevant.size);
+        for (let i = 0; i < idealCount; i++) {
+            idcg += 1 / Math.log2(i + 2);
+        }
+        return idcg === 0 ? 0 : dcg / idcg;
+    }
+    function evaluateConfig(configLabel, searchFn) {
+        let totalRecall1 = 0, totalRecall3 = 0, totalRecall5 = 0, totalMap5 = 0, totalNdcg5 = 0;
+        for (const { query, relevant } of EVAL_QUERIES) {
+            const relevantSet = new Set(relevant);
+            const ranked = searchFn(query);
+            totalRecall1 += recallAtK(ranked, relevantSet, 1);
+            totalRecall3 += recallAtK(ranked, relevantSet, 3);
+            totalRecall5 += recallAtK(ranked, relevantSet, 5);
+            totalMap5 += averagePrecisionAtK(ranked, relevantSet, 5);
+            totalNdcg5 += ndcgAtK(ranked, relevantSet, 5);
+        }
+        const n = EVAL_QUERIES.length;
+        return {
+            recall1: totalRecall1 / n,
+            recall3: totalRecall3 / n,
+            recall5: totalRecall5 / n,
+            map5: totalMap5 / n,
+            ndcg5: totalNdcg5 / n,
+        };
+    }
+    afterEach(() => {
+        resetEmbedding();
+        _resetCooccurrenceCache();
+        _resetWrrfParamsForTesting();
+    });
+    it("hybrid search (lexical only) meets minimum IR thresholds", () => {
+        // Baseline: no embeddings, pure lexical ensemble (keyword + fuzzy + n-gram + semantic + dense)
+        resetEmbedding();
+        const metrics = evaluateConfig("lexical-only", (query) => {
+            const results = hybridSearch(query, toolDescs, { mode: "hybrid", limit: 10 });
+            return results.map((r) => r.name);
+        });
+        // Minimum thresholds for our 14-strategy lexical ensemble
+        // These are regression guards — if we drop below, something broke.
+        expect(metrics.recall5).toBeGreaterThanOrEqual(0.55);
+        expect(metrics.map5).toBeGreaterThanOrEqual(0.40);
+        expect(metrics.ndcg5).toBeGreaterThanOrEqual(0.50);
+    });
+    it("hybrid + embedding search improves over lexical-only baseline", () => {
+        // Build a realistic mock index: tools close to their own category
+        const categories = new Set(ALL_REGISTRY_ENTRIES.map((e) => e.category));
+        const catList = [...categories];
+        // Each category gets a unique direction in a high-dim space
+        const mockIndex = toolDescs.map((t) => {
+            const entry = TOOL_REGISTRY.get(t.name);
+            const catIdx = catList.indexOf(entry?.category ?? "");
+            // Tools in same category share a similar vector direction
+            const vec = new Float32Array(catList.length + 1);
+            if (catIdx >= 0)
+                vec[catIdx] = 0.8;
+            vec[catList.length] = 0.2; // small shared component
+            // Normalize
+            let norm = 0;
+            for (let i = 0; i < vec.length; i++)
+                norm += vec[i] * vec[i];
+            norm = Math.sqrt(norm);
+            for (let i = 0; i < vec.length; i++)
+                vec[i] /= norm;
+            return { name: t.name, vector: vec, nodeType: "tool" };
+        });
+        const domainIndex = catList.map((cat, catIdx) => {
+            const vec = new Float32Array(catList.length + 1);
+            vec[catIdx] = 0.9;
+            vec[catList.length] = 0.1;
+            let norm = 0;
+            for (let i = 0; i < vec.length; i++)
+                norm += vec[i] * vec[i];
+            norm = Math.sqrt(norm);
+            for (let i = 0; i < vec.length; i++)
+                vec[i] /= norm;
+            return { name: `domain:${cat}`, vector: vec, nodeType: "domain" };
+        });
+        _setIndexForTesting([...mockIndex, ...domainIndex]);
+        // Lexical baseline
+        resetEmbedding();
+        const lexicalMetrics = evaluateConfig("lexical", (query) => {
+            const results = hybridSearch(query, toolDescs, { mode: "hybrid", limit: 10 });
+            return results.map((r) => r.name);
+        });
+        // Hybrid + embedding
+        _setIndexForTesting([...mockIndex, ...domainIndex]);
+        const embeddingMetrics = evaluateConfig("hybrid+embedding", (query) => {
+            // Simulate query embedding: average of relevant category vectors
+            const queryWords = query.toLowerCase().split(/\s+/);
+            const queryVec = new Float32Array(catList.length + 1);
+            for (const cat of catList) {
+                if (queryWords.some((w) => cat.includes(w) || w.includes(cat.slice(0, 4)))) {
+                    queryVec[catList.indexOf(cat)] = 0.7;
+                }
+            }
+            queryVec[catList.length] = 0.3;
+            let norm = 0;
+            for (let i = 0; i < queryVec.length; i++)
+                norm += queryVec[i] * queryVec[i];
+            norm = Math.sqrt(norm) || 1;
+            for (let i = 0; i < queryVec.length; i++)
+                queryVec[i] /= norm;
+            const results = hybridSearch(query, toolDescs, {
+                mode: "hybrid",
+                limit: 10,
+                embeddingQueryVec: queryVec,
+            });
+            return results.map((r) => r.name);
+        });
+        // Embedding should not degrade any metric (non-regression)
+        expect(embeddingMetrics.ndcg5).toBeGreaterThanOrEqual(lexicalMetrics.ndcg5 - 0.02);
+    });
+});
+// ── wRRF α ratio ablation: paper vs our calibration ──────────────────────
+// Agent-as-a-Graph (arxiv:2511.18194) optimal: α_A=1.5, α_T=1.0, K=60
+// Our calibration: α_T=1.0, α_D=0.6, K=20
+//
+// The paper optimizes for agent SELECTION across 70 MCP servers.
+// We optimize for tool RETRIEVAL within a single server.
+// This ablation verifies our deviation is justified by measuring Recall@5.
+describe("wRRF α ratio ablation: paper vs NodeBench calibration", () => {
+    const ABLATION_QUERIES = [
+        { query: "verify my implementation", relevant: ["start_verification_cycle", "get_verification_status", "log_test_result"] },
+        { query: "search past findings", relevant: ["search_all_knowledge", "record_learning", "load_session_notes"] },
+        { query: "run security checks", relevant: ["scan_dependencies", "run_code_analysis", "scan_terminal_security"] },
+        { query: "coordinate parallel work", relevant: ["claim_agent_task", "get_parallel_status", "assign_agent_role"] },
+        { query: "capture UI screenshots", relevant: ["capture_screenshot", "capture_full_page", "compare_screenshots"] },
+        { query: "review git compliance", relevant: ["check_git_compliance", "enforce_merge_gate", "review_pr_checklist"] },
+        { query: "write academic paper", relevant: ["polish_academic_text", "check_paper_logic", "generate_academic_caption"] },
+        { query: "check website performance", relevant: ["seo_audit_url", "check_page_performance", "analyze_seo_content"] },
+    ];
+    function buildCategoryAwareIndex() {
+        const categories = new Set(ALL_REGISTRY_ENTRIES.map((e) => e.category));
+        const catList = [...categories];
+        const toolEntries = toolDescs.map((t) => {
+            const entry = TOOL_REGISTRY.get(t.name);
+            const catIdx = catList.indexOf(entry?.category ?? "");
+            const vec = new Float32Array(catList.length);
+            if (catIdx >= 0)
+                vec[catIdx] = 0.85;
+            // Add small noise per tool so not all tools in same cat have identical vectors
+            const nameHash = t.name.split("").reduce((h, c) => ((h << 5) - h + c.charCodeAt(0)) | 0, 0);
+            vec[Math.abs(nameHash) % catList.length] += 0.1;
+            let norm = 0;
+            for (let i = 0; i < vec.length; i++)
+                norm += vec[i] * vec[i];
+            norm = Math.sqrt(norm);
+            for (let i = 0; i < vec.length; i++)
+                vec[i] /= norm;
+            return { name: t.name, vector: vec, nodeType: "tool" };
+        });
+        const domainEntries = catList.map((cat, catIdx) => {
+            const vec = new Float32Array(catList.length);
+            vec[catIdx] = 0.95;
+            let norm = 0;
+            for (let i = 0; i < vec.length; i++)
+                norm += vec[i] * vec[i];
+            norm = Math.sqrt(norm);
+            for (let i = 0; i < vec.length; i++)
+                vec[i] /= norm;
+            return { name: `domain:${cat}`, vector: vec, nodeType: "domain" };
+        });
+        return [...toolEntries, ...domainEntries];
+    }
+    function makeQueryVec(query, catList) {
+        const words = query.toLowerCase().split(/\s+/);
+        const vec = new Float32Array(catList.length);
+        for (const cat of catList) {
+            if (words.some((w) => cat.includes(w) || w.includes(cat.slice(0, 4)))) {
+                vec[catList.indexOf(cat)] = 0.8;
+            }
+        }
+        let norm = 0;
+        for (let i = 0; i < vec.length; i++)
+            norm += vec[i] * vec[i];
+        norm = Math.sqrt(norm) || 1;
+        for (let i = 0; i < vec.length; i++)
+            vec[i] /= norm;
+        return vec;
+    }
+    function runAblation(label) {
+        const catList = [...new Set(ALL_REGISTRY_ENTRIES.map((e) => e.category))];
+        let totalRecall = 0;
+        for (const { query, relevant } of ABLATION_QUERIES) {
+            const relevantSet = new Set(relevant);
+            const queryVec = makeQueryVec(query, catList);
+            const results = hybridSearch(query, toolDescs, {
+                mode: "hybrid",
+                limit: 10,
+                embeddingQueryVec: queryVec,
+            });
+            const topK = results.slice(0, 5).map((r) => r.name);
+            const found = topK.filter((n) => relevantSet.has(n)).length;
+            totalRecall += found / relevantSet.size;
+        }
+        return totalRecall / ABLATION_QUERIES.length;
+    }
+    afterEach(() => {
+        resetEmbedding();
+        _resetWrrfParamsForTesting();
+    });
+    it("ablation grid: find optimal α_D and K for single-server tool retrieval", () => {
+        const mockIndex = buildCategoryAwareIndex();
+        const configs = [
+            { label: "old(T=1.0,D=0.6,K=20)", alphaT: 1.0, alphaD: 0.6, k: 20 },
+            { label: "paper(T=1.0,D=1.5,K=60)", alphaT: 1.0, alphaD: 1.5, k: 60 },
+            { label: "paperK20(T=1.0,D=1.5,K=20)", alphaT: 1.0, alphaD: 1.5, k: 20 },
+            { label: "balanced(T=1.0,D=1.0,K=20)", alphaT: 1.0, alphaD: 1.0, k: 20 },
+            { label: "gentleDom(T=1.0,D=1.2,K=20)", alphaT: 1.0, alphaD: 1.2, k: 20 },
+            { label: "strongDom(T=1.0,D=2.0,K=20)", alphaT: 1.0, alphaD: 2.0, k: 20 },
+        ];
+        const results = [];
+        for (const cfg of configs) {
+            _setIndexForTesting(mockIndex);
+            _setWrrfParamsForTesting({ alphaT: cfg.alphaT, alphaD: cfg.alphaD, k: cfg.k });
+            results.push({ label: cfg.label, recall: runAblation(cfg.label) });
+        }
+        // Sort by recall descending to find winner
+        results.sort((a, b) => b.recall - a.recall);
+        console.log(`wRRF ablation grid — Recall@5:\n${results.map((r) => `  ${r.label}: ${r.recall.toFixed(3)}`).join("\n")}`);
+        // The winning config should be used as our production default.
+        // Assert the winner beats the old default by at least not being worse.
+        const oldResult = results.find((r) => r.label.startsWith("old"));
+        const bestResult = results[0];
+        expect(bestResult.recall).toBeGreaterThanOrEqual(oldResult.recall);
+    });
+});
 //# sourceMappingURL=tools.test.js.map