@kolisachint/hoocode-agent 0.4.141 → 0.4.143

package/dist/core/search/hybrid-search.js

@@ -0,0 +1,158 @@
+/**
+ * Hybrid search orchestrator: resolve mode, run retrievers in parallel, fuse
+ * by rank, expand within budget, trace everything
+ * (docs/hybrid-retrieval-design.md).
+ *
+ * Single-retriever modes flow through the same pipeline — rrfFuse over one
+ * list preserves its order — so lexical, semantic, and hybrid all produce the
+ * same result shape and the same trace record.
+ *
+ * `retrieveCandidates` is the candidate-level core (also used by the eval
+ * harness, which needs forced modes, a configurable `k`, and no trace
+ * pollution); `runSearch` wraps it with span expansion and tracing for the
+ * tool.
+ */
+import { adaptGrepHits } from "./adapter.js";
+import { assembleContext } from "./context-assembler.js";
+import { runLexicalRetriever } from "./lexical-retriever.js";
+import { resolveSearchMode } from "./mode.js";
+import { rerankCandidates } from "./rerank.js";
+import { DEFAULT_RRF_K, rrfFuse } from "./rrf.js";
+import { writeSearchTrace } from "./trace.js";
+/** Raw grep line-hits fetched per query (pre-collapse). */
+const LEXICAL_MATCH_LIMIT = 200;
+/** Adapted lexical candidates entering fusion. The eval gate showed the
+ *  uncapped lexical tail diluting hybrid below plain semantic: lexical
+ *  precision is front-loaded by the adapter's term-evidence ranking, while
+ *  RRF weighs a rank-30 lexical candidate like a rank-30 embedding hit. */
+const LEXICAL_FUSION_CAP = 20;
+/** Embedding hits fetched per query — deep enough for fusion to matter. */
+const EMBED_TOP_K = 50;
+/** Fused candidates kept for reranking / final slicing. */
+const FUSED_WINDOW = 50;
+export async function retrieveCandidates(options) {
+    const { cwd, query, service, signal } = options;
+    const requestedMode = options.mode ?? "auto";
+    const limit = Math.max(1, options.limit ?? 10);
+    const rrfK = options.rrfK ?? DEFAULT_RRF_K;
+    const state = service?.getState();
+    const embedAvailable = service?.isAvailable() ?? false;
+    const embedUnavailableReason = state === undefined
+        ? "semantic index is not enabled"
+        : state.phase === "unavailable" || state.phase === "skipped"
+            ? state.reason
+            : state.phase === "idle"
+                ? "semantic index has not started"
+                : undefined;
+    const resolution = resolveSearchMode(query, requestedMode, embedAvailable, embedUnavailableReason);
+    const mode = resolution.mode;
+    // Map lexical hits onto indexed chunk ids whenever the sidecar is usable,
+    // even in lexical-only mode, so identities line up across modes.
+    const lookupChunk = embedAvailable
+        ? (rel, line) => service.findEnclosingChunk(rel, line)
+        : undefined;
+    const spans = new Map();
+    const lists = [];
+    const retrieverStats = {};
+    const errors = [];
+    const runLexical = async () => {
+        const startedMs = Date.now();
+        try {
+            const lineHits = await runLexicalRetriever(cwd, query, LEXICAL_MATCH_LIMIT, signal);
+            const adapted = adaptGrepHits(lineHits, lookupChunk);
+            // In single-retriever lexical mode the full list is the result; in
+            // hybrid, only the front-loaded head is trustworthy enough to vote.
+            const hits = mode === "hybrid" ? adapted.hits.slice(0, LEXICAL_FUSION_CAP) : adapted.hits;
+            for (const [id, span] of adapted.spans)
+                if (!spans.has(id))
+                    spans.set(id, span);
+            lists.push(hits);
+            retrieverStats.grep = { latencyMs: Date.now() - startedMs, hitCount: hits.length };
+        }
+        catch (e) {
+            errors.push(e instanceof Error ? e : new Error(String(e)));
+            retrieverStats.grep = { latencyMs: Date.now() - startedMs, hitCount: 0 };
+        }
+    };
+    const runEmbed = async () => {
+        const startedMs = Date.now();
+        try {
+            const chunkHits = await service.searchChunks(query, EMBED_TOP_K);
+            const hits = chunkHits.map((hit, i) => ({
+                id: hit.id,
+                rank: i + 1,
+                score: hit.score,
+                source: "embed",
+            }));
+            for (const hit of chunkHits) {
+                spans.set(hit.id, { path: hit.path, startLine: hit.startLine, endLine: hit.endLine });
+            }
+            lists.push(hits);
+            retrieverStats.embed = { latencyMs: Date.now() - startedMs, hitCount: hits.length };
+        }
+        catch (e) {
+            errors.push(e instanceof Error ? e : new Error(String(e)));
+            retrieverStats.embed = { latencyMs: Date.now() - startedMs, hitCount: 0 };
+        }
+    };
+    const runs = [];
+    if (mode === "lexical" || mode === "hybrid")
+        runs.push(runLexical());
+    if (mode === "semantic" || mode === "hybrid")
+        runs.push(runEmbed());
+    await Promise.all(runs);
+    if (signal?.aborted)
+        throw new Error("Operation aborted");
+    // A partial failure in hybrid degrades to whichever retriever survived;
+    // only a total loss is an error.
+    if (lists.length === 0)
+        throw errors[0] ?? new Error("search produced no retriever results");
+    const fused = rrfFuse(lists, rrfK).slice(0, FUSED_WINDOW);
+    let candidates = [];
+    for (const hit of fused) {
+        const span = spans.get(hit.id);
+        if (span)
+            candidates.push({ ...hit, ...span });
+    }
+    let rerankInfo;
+    if (options.rerank !== false) {
+        const reranked = rerankCandidates(query, candidates, cwd);
+        rerankInfo = { applied: true, candidateCount: candidates.length, latencyMs: reranked.latencyMs };
+        candidates = reranked.candidates;
+    }
+    candidates = candidates.slice(0, limit);
+    return {
+        candidates,
+        resolvedMode: mode,
+        degradedReason: resolution.degradedReason,
+        indexPhase: state?.phase === "ready" ? "ready" : state?.phase === "indexing" ? "indexing" : "unavailable",
+        retrievers: retrieverStats,
+        indexing: state?.phase === "indexing" ? { done: state.done, total: state.total } : undefined,
+        rrfK,
+        rerank: rerankInfo,
+    };
+}
+export async function runSearch(options) {
+    const retrieved = await retrieveCandidates(options);
+    const assembled = assembleContext(retrieved.candidates, { cwd: options.cwd, tokenBudget: options.tokenBudget });
+    writeSearchTrace(options.cwd, {
+        timestampMs: Date.now(),
+        query: options.query,
+        requestedMode: options.mode ?? "auto",
+        resolvedMode: retrieved.resolvedMode,
+        degradedReason: retrieved.degradedReason,
+        indexPhase: retrieved.indexPhase,
+        rrfK: retrieved.resolvedMode === "hybrid" ? retrieved.rrfK : undefined,
+        retrievers: retrieved.retrievers,
+        fused: retrieved.candidates.map(({ id, rrfScore, ranks, rawScores }) => ({ id, rrfScore, ranks, rawScores })),
+        rerank: retrieved.rerank,
+    });
+    return {
+        text: assembled.text,
+        resolvedMode: retrieved.resolvedMode,
+        degradedReason: retrieved.degradedReason,
+        resultCount: retrieved.candidates.length,
+        indexing: retrieved.indexing,
+    };
+}
+//# sourceMappingURL=hybrid-search.js.map

package/dist/core/search/hybrid-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-search.js","sourceRoot":"","sources":["../../../src/core/search/hybrid-search.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Hybrid search orchestrator: resolve mode, run retrievers in parallel, fuse\n * by rank, expand within budget, trace everything\n * (docs/hybrid-retrieval-design.md).\n *\n * Single-retriever modes flow through the same pipeline — rrfFuse over one\n * list preserves its order — so lexical, semantic, and hybrid all produce the\n * same result shape and the same trace record.\n *\n * `retrieveCandidates` is the candidate-level core (also used by the eval\n * harness, which needs forced modes, a configurable `k`, and no trace\n * pollution); `runSearch` wraps it with span expansion and tracing for the\n * tool.\n */\n\nimport type { EmbsearchService } from \"../embsearch/embsearch-service.js\";\nimport { adaptGrepHits, type ChunkLookup } from \"./adapter.js\";\nimport { assembleContext } from \"./context-assembler.js\";\nimport { runLexicalRetriever } from \"./lexical-retriever.js\";\nimport { resolveSearchMode } from \"./mode.js\";\nimport { rerankCandidates } from \"./rerank.js\";\nimport { DEFAULT_RRF_K, rrfFuse } from \"./rrf.js\";\nimport { writeSearchTrace } from \"./trace.js\";\nimport type { CandidateSpan, FusedCandidate, RankedHit, ResolvedSearchMode, SearchMode, SearchTrace } from \"./types.js\";\n\n/** Raw grep line-hits fetched per query (pre-collapse). */\nconst LEXICAL_MATCH_LIMIT = 200;\n/** Adapted lexical candidates entering fusion. The eval gate showed the\n *  uncapped lexical tail diluting hybrid below plain semantic: lexical\n *  precision is front-loaded by the adapter's term-evidence ranking, while\n *  RRF weighs a rank-30 lexical candidate like a rank-30 embedding hit. */\nconst LEXICAL_FUSION_CAP = 20;\n/** Embedding hits fetched per query — deep enough for fusion to matter. */\nconst EMBED_TOP_K = 50;\n/** Fused candidates kept for reranking / final slicing. */\nconst FUSED_WINDOW = 50;\n\nexport interface RetrieveOptions {\n\tcwd: string;\n\tquery: string;\n\tmode?: SearchMode;\n\t/** Maximum fused candidates returned. */\n\tlimit?: number;\n\t/** RRF constant override (eval harness sweeps this). Default: 60. */\n\trrfK?: number;\n\t/** Rerank the fused top-50 before slicing to `limit`. Default: true. */\n\trerank?: boolean;\n\tservice?: EmbsearchService;\n\tsignal?: AbortSignal;\n}\n\nexport interface RetrieveResult {\n\tcandidates: FusedCandidate[];\n\tresolvedMode: ResolvedSearchMode;\n\tdegradedReason?: string;\n\tindexPhase: SearchTrace[\"indexPhase\"];\n\tretrievers: SearchTrace[\"retrievers\"];\n\t/** Set while the embedding index is still building. */\n\tindexing?: { done: number; total: number };\n\trrfK: number;\n\trerank?: SearchTrace[\"rerank\"];\n}\n\nexport interface RunSearchOptions extends RetrieveOptions {\n\t/** Approximate token budget for the result text. */\n\ttokenBudget?: number;\n}\n\nexport interface RunSearchResult {\n\ttext: string;\n\tresolvedMode: ResolvedSearchMode;\n\tdegradedReason?: string;\n\tresultCount: number;\n\t/** Set while the embedding index is still building. */\n\tindexing?: { done: number; total: number };\n}\n\nexport async function retrieveCandidates(options: RetrieveOptions): Promise<RetrieveResult> {\n\tconst { cwd, query, service, signal } = options;\n\tconst requestedMode = options.mode ?? \"auto\";\n\tconst limit = Math.max(1, options.limit ?? 10);\n\tconst rrfK = options.rrfK ?? DEFAULT_RRF_K;\n\n\tconst state = service?.getState();\n\tconst embedAvailable = service?.isAvailable() ?? false;\n\tconst embedUnavailableReason =\n\t\tstate === undefined\n\t\t\t? \"semantic index is not enabled\"\n\t\t\t: state.phase === \"unavailable\" || state.phase === \"skipped\"\n\t\t\t\t? state.reason\n\t\t\t\t: state.phase === \"idle\"\n\t\t\t\t\t? \"semantic index has not started\"\n\t\t\t\t\t: undefined;\n\n\tconst resolution = resolveSearchMode(query, requestedMode, embedAvailable, embedUnavailableReason);\n\tconst mode = resolution.mode;\n\n\t// Map lexical hits onto indexed chunk ids whenever the sidecar is usable,\n\t// even in lexical-only mode, so identities line up across modes.\n\tconst lookupChunk: ChunkLookup | undefined = embedAvailable\n\t\t? (rel, line) => service!.findEnclosingChunk(rel, line)\n\t\t: undefined;\n\n\tconst spans = new Map<string, CandidateSpan>();\n\tconst lists: RankedHit[][] = [];\n\tconst retrieverStats: SearchTrace[\"retrievers\"] = {};\n\tconst errors: Error[] = [];\n\n\tconst runLexical = async (): Promise<void> => {\n\t\tconst startedMs = Date.now();\n\t\ttry {\n\t\t\tconst lineHits = await runLexicalRetriever(cwd, query, LEXICAL_MATCH_LIMIT, signal);\n\t\t\tconst adapted = adaptGrepHits(lineHits, lookupChunk);\n\t\t\t// In single-retriever lexical mode the full list is the result; in\n\t\t\t// hybrid, only the front-loaded head is trustworthy enough to vote.\n\t\t\tconst hits = mode === \"hybrid\" ? adapted.hits.slice(0, LEXICAL_FUSION_CAP) : adapted.hits;\n\t\t\tfor (const [id, span] of adapted.spans) if (!spans.has(id)) spans.set(id, span);\n\t\t\tlists.push(hits);\n\t\t\tretrieverStats.grep = { latencyMs: Date.now() - startedMs, hitCount: hits.length };\n\t\t} catch (e) {\n\t\t\terrors.push(e instanceof Error ? e : new Error(String(e)));\n\t\t\tretrieverStats.grep = { latencyMs: Date.now() - startedMs, hitCount: 0 };\n\t\t}\n\t};\n\n\tconst runEmbed = async (): Promise<void> => {\n\t\tconst startedMs = Date.now();\n\t\ttry {\n\t\t\tconst chunkHits = await service!.searchChunks(query, EMBED_TOP_K);\n\t\t\tconst hits: RankedHit[] = chunkHits.map((hit, i) => ({\n\t\t\t\tid: hit.id,\n\t\t\t\trank: i + 1,\n\t\t\t\tscore: hit.score,\n\t\t\t\tsource: \"embed\",\n\t\t\t}));\n\t\t\tfor (const hit of chunkHits) {\n\t\t\t\tspans.set(hit.id, { path: hit.path, startLine: hit.startLine, endLine: hit.endLine });\n\t\t\t}\n\t\t\tlists.push(hits);\n\t\t\tretrieverStats.embed = { latencyMs: Date.now() - startedMs, hitCount: hits.length };\n\t\t} catch (e) {\n\t\t\terrors.push(e instanceof Error ? e : new Error(String(e)));\n\t\t\tretrieverStats.embed = { latencyMs: Date.now() - startedMs, hitCount: 0 };\n\t\t}\n\t};\n\n\tconst runs: Promise<void>[] = [];\n\tif (mode === \"lexical\" || mode === \"hybrid\") runs.push(runLexical());\n\tif (mode === \"semantic\" || mode === \"hybrid\") runs.push(runEmbed());\n\tawait Promise.all(runs);\n\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t// A partial failure in hybrid degrades to whichever retriever survived;\n\t// only a total loss is an error.\n\tif (lists.length === 0) throw errors[0] ?? new Error(\"search produced no retriever results\");\n\n\tconst fused = rrfFuse(lists, rrfK).slice(0, FUSED_WINDOW);\n\tlet candidates: FusedCandidate[] = [];\n\tfor (const hit of fused) {\n\t\tconst span = spans.get(hit.id);\n\t\tif (span) candidates.push({ ...hit, ...span });\n\t}\n\n\tlet rerankInfo: SearchTrace[\"rerank\"];\n\tif (options.rerank !== false) {\n\t\tconst reranked = rerankCandidates(query, candidates, cwd);\n\t\trerankInfo = { applied: true, candidateCount: candidates.length, latencyMs: reranked.latencyMs };\n\t\tcandidates = reranked.candidates;\n\t}\n\tcandidates = candidates.slice(0, limit);\n\n\treturn {\n\t\tcandidates,\n\t\tresolvedMode: mode,\n\t\tdegradedReason: resolution.degradedReason,\n\t\tindexPhase: state?.phase === \"ready\" ? \"ready\" : state?.phase === \"indexing\" ? \"indexing\" : \"unavailable\",\n\t\tretrievers: retrieverStats,\n\t\tindexing: state?.phase === \"indexing\" ? { done: state.done, total: state.total } : undefined,\n\t\trrfK,\n\t\trerank: rerankInfo,\n\t};\n}\n\nexport async function runSearch(options: RunSearchOptions): Promise<RunSearchResult> {\n\tconst retrieved = await retrieveCandidates(options);\n\n\tconst assembled = assembleContext(retrieved.candidates, { cwd: options.cwd, tokenBudget: options.tokenBudget });\n\n\twriteSearchTrace(options.cwd, {\n\t\ttimestampMs: Date.now(),\n\t\tquery: options.query,\n\t\trequestedMode: options.mode ?? \"auto\",\n\t\tresolvedMode: retrieved.resolvedMode,\n\t\tdegradedReason: retrieved.degradedReason,\n\t\tindexPhase: retrieved.indexPhase,\n\t\trrfK: retrieved.resolvedMode === \"hybrid\" ? retrieved.rrfK : undefined,\n\t\tretrievers: retrieved.retrievers,\n\t\tfused: retrieved.candidates.map(({ id, rrfScore, ranks, rawScores }) => ({ id, rrfScore, ranks, rawScores })),\n\t\trerank: retrieved.rerank,\n\t});\n\n\treturn {\n\t\ttext: assembled.text,\n\t\tresolvedMode: retrieved.resolvedMode,\n\t\tdegradedReason: retrieved.degradedReason,\n\t\tresultCount: retrieved.candidates.length,\n\t\tindexing: retrieved.indexing,\n\t};\n}\n"]}

package/dist/core/search/lexical-retriever.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Internal lexical retriever for hybrid search.
+ *
+ * This is not the grep *tool* — it is the lexical recall backend: it turns a
+ * natural query into a ripgrep pattern, streams matches, and returns bare
+ * `rel:line` hits for the grep→chunk adapter. rg drives the fast path; the
+ * pure-JS nativeGrep fallback keeps restricted environments working, same as
+ * the grep tool.
+ */
+import type { GrepLineHit } from "./adapter.js";
+export interface LexicalQueryPlan {
+    /** rg-ready regex pattern. */
+    pattern: string;
+    /** Raw (unescaped, lowercased) terms, for per-line term attribution. */
+    terms: string[];
+}
+/**
+ * Build the retrieval plan for a query: a quoted segment is searched
+ * verbatim; otherwise the longest few identifier-ish tokens are OR-ed
+ * together. Returns undefined when the query yields nothing searchable.
+ */
+export declare function buildLexicalQueryPlan(query: string): LexicalQueryPlan | undefined;
+/** Pattern-only view of {@link buildLexicalQueryPlan}. */
+export declare function buildLexicalPattern(query: string): string | undefined;
+/**
+ * Run lexical retrieval over `cwd`, returning up to `limit` line-hits in
+ * output order with POSIX repo-relative paths.
+ */
+export declare function runLexicalRetriever(cwd: string, query: string, limit: number, signal?: AbortSignal): Promise<GrepLineHit[]>;
+//# sourceMappingURL=lexical-retriever.d.ts.map

package/dist/core/search/lexical-retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-retriever.d.ts","sourceRoot":"","sources":["../../../src/core/search/lexical-retriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAWhD,MAAM,WAAW,gBAAgB;IAChC,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,KAAK,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAgBjF;AAED,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErE;AAUD;;;GAGG;AACH,wBAAsB,mBAAmB,CACxC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC,WAAW,EAAE,CAAC,CAkGxB","sourcesContent":["/**\n * Internal lexical retriever for hybrid search.\n *\n * This is not the grep *tool* — it is the lexical recall backend: it turns a\n * natural query into a ripgrep pattern, streams matches, and returns bare\n * `rel:line` hits for the grep→chunk adapter. rg drives the fast path; the\n * pure-JS nativeGrep fallback keeps restricted environments working, same as\n * the grep tool.\n */\n\nimport { createInterface } from \"node:readline\";\nimport { spawn } from \"child_process\";\nimport { readFileSync } from \"fs\";\nimport path from \"path\";\nimport { ensureTool } from \"../../utils/tools-manager.js\";\nimport { isNativeSearchForced, nativeGrep } from \"../tools/native-search.js\";\nimport type { GrepLineHit } from \"./adapter.js\";\n\n/** Terms considered per query (longest first) when building the pattern. */\nconst MAX_TERMS = 4;\n/** Minimum token length worth matching on. */\nconst MIN_TERM_LENGTH = 3;\n\nfunction escapeRegExp(value: string): string {\n\treturn value.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\nexport interface LexicalQueryPlan {\n\t/** rg-ready regex pattern. */\n\tpattern: string;\n\t/** Raw (unescaped, lowercased) terms, for per-line term attribution. */\n\tterms: string[];\n}\n\n/**\n * Build the retrieval plan for a query: a quoted segment is searched\n * verbatim; otherwise the longest few identifier-ish tokens are OR-ed\n * together. Returns undefined when the query yields nothing searchable.\n */\nexport function buildLexicalQueryPlan(query: string): LexicalQueryPlan | undefined {\n\tconst quoted = [...query.matchAll(/[\"'`]([^\"'`]+)[\"'`]/g)]\n\t\t.map((m) => m[1].trim())\n\t\t.filter((s) => s.length > 0)\n\t\t.sort((a, b) => b.length - a.length)[0];\n\tif (quoted) return { pattern: escapeRegExp(quoted), terms: [quoted.toLowerCase()] };\n\n\tconst tokens = [...new Set(query.match(/[A-Za-z0-9_$][\\w$.-]*/g) ?? [])]\n\t\t.filter((t) => t.length >= MIN_TERM_LENGTH)\n\t\t.sort((a, b) => b.length - a.length || a.localeCompare(b))\n\t\t.slice(0, MAX_TERMS);\n\tif (tokens.length === 0) {\n\t\tconst trimmed = query.trim();\n\t\treturn trimmed ? { pattern: escapeRegExp(trimmed), terms: [trimmed.toLowerCase()] } : undefined;\n\t}\n\treturn { pattern: tokens.map(escapeRegExp).join(\"|\"), terms: tokens.map((t) => t.toLowerCase()) };\n}\n\n/** Pattern-only view of {@link buildLexicalQueryPlan}. */\nexport function buildLexicalPattern(query: string): string | undefined {\n\treturn buildLexicalQueryPlan(query)?.pattern;\n}\n\n/** Which plan terms appear on a matched line (retrieval is case-insensitive,\n *  so attribution is too). */\nfunction termsOnLine(plan: LexicalQueryPlan, lineText: string | undefined): string[] {\n\tif (!lineText) return [];\n\tconst lower = lineText.toLowerCase();\n\treturn plan.terms.filter((t) => lower.includes(t));\n}\n\n/**\n * Run lexical retrieval over `cwd`, returning up to `limit` line-hits in\n * output order with POSIX repo-relative paths.\n */\nexport async function runLexicalRetriever(\n\tcwd: string,\n\tquery: string,\n\tlimit: number,\n\tsignal?: AbortSignal,\n): Promise<GrepLineHit[]> {\n\tconst plan = buildLexicalQueryPlan(query);\n\tif (!plan) return [];\n\tconst { pattern } = plan;\n\n\tconst toRel = (filePath: string): string => {\n\t\tconst rel = path.relative(cwd, filePath);\n\t\treturn (rel && !rel.startsWith(\"..\") ? rel : filePath).replace(/\\\\/g, \"/\");\n\t};\n\n\tconst rgPath = isNativeSearchForced() ? undefined : await ensureTool(\"rg\", true);\n\tif (!rgPath) {\n\t\tconst result = await nativeGrep(cwd, {\n\t\t\tpattern,\n\t\t\tisDirectory: true,\n\t\t\tignoreCase: true,\n\t\t\tlimit,\n\t\t\tsignal,\n\t\t\treadFile: (p) => readFileSync(p, \"utf-8\"),\n\t\t});\n\t\treturn result.matches.map((m) => ({\n\t\t\trel: toRel(m.filePath),\n\t\t\tline: m.lineNumber,\n\t\t\tterms: termsOnLine(plan, m.lineText),\n\t\t}));\n\t}\n\n\treturn new Promise<GrepLineHit[]>((resolve, reject) => {\n\t\t// --sort path forces a deterministic (single-threaded) walk: with the\n\t\t// match cap truncating the stream, a parallel walk would return a\n\t\t// different hit subset per run — \"same query, different context\".\n\t\tconst args = [\n\t\t\t\"--json\",\n\t\t\t\"--line-number\",\n\t\t\t\"--color=never\",\n\t\t\t\"--hidden\",\n\t\t\t\"--ignore-case\",\n\t\t\t\"--sort\",\n\t\t\t\"path\",\n\t\t\t\"--\",\n\t\t\tpattern,\n\t\t\tcwd,\n\t\t];\n\t\tconst child = spawn(rgPath, args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\tconst rl = createInterface({ input: child.stdout });\n\t\tconst hits: GrepLineHit[] = [];\n\t\tlet stderr = \"\";\n\t\tlet killedDueToLimit = false;\n\t\tlet aborted = false;\n\n\t\tconst onAbort = () => {\n\t\t\taborted = true;\n\t\t\tif (!child.killed) child.kill();\n\t\t};\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\tchild.stderr?.on(\"data\", (chunk) => {\n\t\t\tstderr += chunk.toString();\n\t\t});\n\n\t\trl.on(\"line\", (line) => {\n\t\t\tif (!line.trim() || hits.length >= limit) return;\n\t\t\tlet event: any;\n\t\t\ttry {\n\t\t\t\tevent = JSON.parse(line);\n\t\t\t} catch {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (event.type !== \"match\") return;\n\t\t\tconst filePath = event.data?.path?.text;\n\t\t\tconst lineNumber = event.data?.line_number;\n\t\t\tif (filePath && typeof lineNumber === \"number\") {\n\t\t\t\thits.push({ rel: toRel(filePath), line: lineNumber, terms: termsOnLine(plan, event.data?.lines?.text) });\n\t\t\t}\n\t\t\tif (hits.length >= limit && !child.killed) {\n\t\t\t\tkilledDueToLimit = true;\n\t\t\t\tchild.kill();\n\t\t\t}\n\t\t});\n\n\t\tchild.on(\"error\", (error) => {\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\treject(new Error(`Failed to run ripgrep: ${error.message}`));\n\t\t});\n\t\tchild.on(\"close\", (code) => {\n\t\t\trl.close();\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tif (aborted) {\n\t\t\t\treject(new Error(\"Operation aborted\"));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\t// rg exits 1 on \"no matches\" — that is a valid empty result.\n\t\t\tif (!killedDueToLimit && code !== 0 && code !== 1) {\n\t\t\t\treject(new Error(stderr.trim() || `ripgrep exited with code ${code}`));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tresolve(hits);\n\t\t});\n\t});\n}\n"]}

package/dist/core/search/lexical-retriever.js

@@ -0,0 +1,159 @@
+/**
+ * Internal lexical retriever for hybrid search.
+ *
+ * This is not the grep *tool* — it is the lexical recall backend: it turns a
+ * natural query into a ripgrep pattern, streams matches, and returns bare
+ * `rel:line` hits for the grep→chunk adapter. rg drives the fast path; the
+ * pure-JS nativeGrep fallback keeps restricted environments working, same as
+ * the grep tool.
+ */
+import { createInterface } from "node:readline";
+import { spawn } from "child_process";
+import { readFileSync } from "fs";
+import path from "path";
+import { ensureTool } from "../../utils/tools-manager.js";
+import { isNativeSearchForced, nativeGrep } from "../tools/native-search.js";
+/** Terms considered per query (longest first) when building the pattern. */
+const MAX_TERMS = 4;
+/** Minimum token length worth matching on. */
+const MIN_TERM_LENGTH = 3;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Build the retrieval plan for a query: a quoted segment is searched
+ * verbatim; otherwise the longest few identifier-ish tokens are OR-ed
+ * together. Returns undefined when the query yields nothing searchable.
+ */
+export function buildLexicalQueryPlan(query) {
+    const quoted = [...query.matchAll(/["'`]([^"'`]+)["'`]/g)]
+        .map((m) => m[1].trim())
+        .filter((s) => s.length > 0)
+        .sort((a, b) => b.length - a.length)[0];
+    if (quoted)
+        return { pattern: escapeRegExp(quoted), terms: [quoted.toLowerCase()] };
+    const tokens = [...new Set(query.match(/[A-Za-z0-9_$][\w$.-]*/g) ?? [])]
+        .filter((t) => t.length >= MIN_TERM_LENGTH)
+        .sort((a, b) => b.length - a.length || a.localeCompare(b))
+        .slice(0, MAX_TERMS);
+    if (tokens.length === 0) {
+        const trimmed = query.trim();
+        return trimmed ? { pattern: escapeRegExp(trimmed), terms: [trimmed.toLowerCase()] } : undefined;
+    }
+    return { pattern: tokens.map(escapeRegExp).join("|"), terms: tokens.map((t) => t.toLowerCase()) };
+}
+/** Pattern-only view of {@link buildLexicalQueryPlan}. */
+export function buildLexicalPattern(query) {
+    return buildLexicalQueryPlan(query)?.pattern;
+}
+/** Which plan terms appear on a matched line (retrieval is case-insensitive,
+ *  so attribution is too). */
+function termsOnLine(plan, lineText) {
+    if (!lineText)
+        return [];
+    const lower = lineText.toLowerCase();
+    return plan.terms.filter((t) => lower.includes(t));
+}
+/**
+ * Run lexical retrieval over `cwd`, returning up to `limit` line-hits in
+ * output order with POSIX repo-relative paths.
+ */
+export async function runLexicalRetriever(cwd, query, limit, signal) {
+    const plan = buildLexicalQueryPlan(query);
+    if (!plan)
+        return [];
+    const { pattern } = plan;
+    const toRel = (filePath) => {
+        const rel = path.relative(cwd, filePath);
+        return (rel && !rel.startsWith("..") ? rel : filePath).replace(/\\/g, "/");
+    };
+    const rgPath = isNativeSearchForced() ? undefined : await ensureTool("rg", true);
+    if (!rgPath) {
+        const result = await nativeGrep(cwd, {
+            pattern,
+            isDirectory: true,
+            ignoreCase: true,
+            limit,
+            signal,
+            readFile: (p) => readFileSync(p, "utf-8"),
+        });
+        return result.matches.map((m) => ({
+            rel: toRel(m.filePath),
+            line: m.lineNumber,
+            terms: termsOnLine(plan, m.lineText),
+        }));
+    }
+    return new Promise((resolve, reject) => {
+        // --sort path forces a deterministic (single-threaded) walk: with the
+        // match cap truncating the stream, a parallel walk would return a
+        // different hit subset per run — "same query, different context".
+        const args = [
+            "--json",
+            "--line-number",
+            "--color=never",
+            "--hidden",
+            "--ignore-case",
+            "--sort",
+            "path",
+            "--",
+            pattern,
+            cwd,
+        ];
+        const child = spawn(rgPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const rl = createInterface({ input: child.stdout });
+        const hits = [];
+        let stderr = "";
+        let killedDueToLimit = false;
+        let aborted = false;
+        const onAbort = () => {
+            aborted = true;
+            if (!child.killed)
+                child.kill();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        rl.on("line", (line) => {
+            if (!line.trim() || hits.length >= limit)
+                return;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (event.type !== "match")
+                return;
+            const filePath = event.data?.path?.text;
+            const lineNumber = event.data?.line_number;
+            if (filePath && typeof lineNumber === "number") {
+                hits.push({ rel: toRel(filePath), line: lineNumber, terms: termsOnLine(plan, event.data?.lines?.text) });
+            }
+            if (hits.length >= limit && !child.killed) {
+                killedDueToLimit = true;
+                child.kill();
+            }
+        });
+        child.on("error", (error) => {
+            signal?.removeEventListener("abort", onAbort);
+            reject(new Error(`Failed to run ripgrep: ${error.message}`));
+        });
+        child.on("close", (code) => {
+            rl.close();
+            signal?.removeEventListener("abort", onAbort);
+            if (aborted) {
+                reject(new Error("Operation aborted"));
+                return;
+            }
+            // rg exits 1 on "no matches" — that is a valid empty result.
+            if (!killedDueToLimit && code !== 0 && code !== 1) {
+                reject(new Error(stderr.trim() || `ripgrep exited with code ${code}`));
+                return;
+            }
+            resolve(hits);
+        });
+    });
+}
+//# sourceMappingURL=lexical-retriever.js.map

package/dist/core/search/lexical-retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical-retriever.js","sourceRoot":"","sources":["../../../src/core/search/lexical-retriever.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Internal lexical retriever for hybrid search.\n *\n * This is not the grep *tool* — it is the lexical recall backend: it turns a\n * natural query into a ripgrep pattern, streams matches, and returns bare\n * `rel:line` hits for the grep→chunk adapter. rg drives the fast path; the\n * pure-JS nativeGrep fallback keeps restricted environments working, same as\n * the grep tool.\n */\n\nimport { createInterface } from \"node:readline\";\nimport { spawn } from \"child_process\";\nimport { readFileSync } from \"fs\";\nimport path from \"path\";\nimport { ensureTool } from \"../../utils/tools-manager.js\";\nimport { isNativeSearchForced, nativeGrep } from \"../tools/native-search.js\";\nimport type { GrepLineHit } from \"./adapter.js\";\n\n/** Terms considered per query (longest first) when building the pattern. */\nconst MAX_TERMS = 4;\n/** Minimum token length worth matching on. */\nconst MIN_TERM_LENGTH = 3;\n\nfunction escapeRegExp(value: string): string {\n\treturn value.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\nexport interface LexicalQueryPlan {\n\t/** rg-ready regex pattern. */\n\tpattern: string;\n\t/** Raw (unescaped, lowercased) terms, for per-line term attribution. */\n\tterms: string[];\n}\n\n/**\n * Build the retrieval plan for a query: a quoted segment is searched\n * verbatim; otherwise the longest few identifier-ish tokens are OR-ed\n * together. Returns undefined when the query yields nothing searchable.\n */\nexport function buildLexicalQueryPlan(query: string): LexicalQueryPlan | undefined {\n\tconst quoted = [...query.matchAll(/[\"'`]([^\"'`]+)[\"'`]/g)]\n\t\t.map((m) => m[1].trim())\n\t\t.filter((s) => s.length > 0)\n\t\t.sort((a, b) => b.length - a.length)[0];\n\tif (quoted) return { pattern: escapeRegExp(quoted), terms: [quoted.toLowerCase()] };\n\n\tconst tokens = [...new Set(query.match(/[A-Za-z0-9_$][\\w$.-]*/g) ?? [])]\n\t\t.filter((t) => t.length >= MIN_TERM_LENGTH)\n\t\t.sort((a, b) => b.length - a.length || a.localeCompare(b))\n\t\t.slice(0, MAX_TERMS);\n\tif (tokens.length === 0) {\n\t\tconst trimmed = query.trim();\n\t\treturn trimmed ? { pattern: escapeRegExp(trimmed), terms: [trimmed.toLowerCase()] } : undefined;\n\t}\n\treturn { pattern: tokens.map(escapeRegExp).join(\"|\"), terms: tokens.map((t) => t.toLowerCase()) };\n}\n\n/** Pattern-only view of {@link buildLexicalQueryPlan}. */\nexport function buildLexicalPattern(query: string): string | undefined {\n\treturn buildLexicalQueryPlan(query)?.pattern;\n}\n\n/** Which plan terms appear on a matched line (retrieval is case-insensitive,\n *  so attribution is too). */\nfunction termsOnLine(plan: LexicalQueryPlan, lineText: string | undefined): string[] {\n\tif (!lineText) return [];\n\tconst lower = lineText.toLowerCase();\n\treturn plan.terms.filter((t) => lower.includes(t));\n}\n\n/**\n * Run lexical retrieval over `cwd`, returning up to `limit` line-hits in\n * output order with POSIX repo-relative paths.\n */\nexport async function runLexicalRetriever(\n\tcwd: string,\n\tquery: string,\n\tlimit: number,\n\tsignal?: AbortSignal,\n): Promise<GrepLineHit[]> {\n\tconst plan = buildLexicalQueryPlan(query);\n\tif (!plan) return [];\n\tconst { pattern } = plan;\n\n\tconst toRel = (filePath: string): string => {\n\t\tconst rel = path.relative(cwd, filePath);\n\t\treturn (rel && !rel.startsWith(\"..\") ? rel : filePath).replace(/\\\\/g, \"/\");\n\t};\n\n\tconst rgPath = isNativeSearchForced() ? undefined : await ensureTool(\"rg\", true);\n\tif (!rgPath) {\n\t\tconst result = await nativeGrep(cwd, {\n\t\t\tpattern,\n\t\t\tisDirectory: true,\n\t\t\tignoreCase: true,\n\t\t\tlimit,\n\t\t\tsignal,\n\t\t\treadFile: (p) => readFileSync(p, \"utf-8\"),\n\t\t});\n\t\treturn result.matches.map((m) => ({\n\t\t\trel: toRel(m.filePath),\n\t\t\tline: m.lineNumber,\n\t\t\tterms: termsOnLine(plan, m.lineText),\n\t\t}));\n\t}\n\n\treturn new Promise<GrepLineHit[]>((resolve, reject) => {\n\t\t// --sort path forces a deterministic (single-threaded) walk: with the\n\t\t// match cap truncating the stream, a parallel walk would return a\n\t\t// different hit subset per run — \"same query, different context\".\n\t\tconst args = [\n\t\t\t\"--json\",\n\t\t\t\"--line-number\",\n\t\t\t\"--color=never\",\n\t\t\t\"--hidden\",\n\t\t\t\"--ignore-case\",\n\t\t\t\"--sort\",\n\t\t\t\"path\",\n\t\t\t\"--\",\n\t\t\tpattern,\n\t\t\tcwd,\n\t\t];\n\t\tconst child = spawn(rgPath, args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\tconst rl = createInterface({ input: child.stdout });\n\t\tconst hits: GrepLineHit[] = [];\n\t\tlet stderr = \"\";\n\t\tlet killedDueToLimit = false;\n\t\tlet aborted = false;\n\n\t\tconst onAbort = () => {\n\t\t\taborted = true;\n\t\t\tif (!child.killed) child.kill();\n\t\t};\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\tchild.stderr?.on(\"data\", (chunk) => {\n\t\t\tstderr += chunk.toString();\n\t\t});\n\n\t\trl.on(\"line\", (line) => {\n\t\t\tif (!line.trim() || hits.length >= limit) return;\n\t\t\tlet event: any;\n\t\t\ttry {\n\t\t\t\tevent = JSON.parse(line);\n\t\t\t} catch {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (event.type !== \"match\") return;\n\t\t\tconst filePath = event.data?.path?.text;\n\t\t\tconst lineNumber = event.data?.line_number;\n\t\t\tif (filePath && typeof lineNumber === \"number\") {\n\t\t\t\thits.push({ rel: toRel(filePath), line: lineNumber, terms: termsOnLine(plan, event.data?.lines?.text) });\n\t\t\t}\n\t\t\tif (hits.length >= limit && !child.killed) {\n\t\t\t\tkilledDueToLimit = true;\n\t\t\t\tchild.kill();\n\t\t\t}\n\t\t});\n\n\t\tchild.on(\"error\", (error) => {\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\treject(new Error(`Failed to run ripgrep: ${error.message}`));\n\t\t});\n\t\tchild.on(\"close\", (code) => {\n\t\t\trl.close();\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tif (aborted) {\n\t\t\t\treject(new Error(\"Operation aborted\"));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\t// rg exits 1 on \"no matches\" — that is a valid empty result.\n\t\t\tif (!killedDueToLimit && code !== 0 && code !== 1) {\n\t\t\t\treject(new Error(stderr.trim() || `ripgrep exited with code ${code}`));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tresolve(hits);\n\t\t});\n\t});\n}\n"]}

package/dist/core/search/mode.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Availability-first search mode resolution
+ * (docs/hybrid-retrieval-design.md, Decision 4).
+ *
+ * No clever query router: with a hot local daemon, running both retrievers
+ * costs one extra embedding query, while misrouting costs recall. `auto`
+ * therefore means hybrid whenever the index is available, dropping to lexical
+ * only on strong lexical signals. Requested semantic/hybrid degrade to
+ * lexical (with a recorded reason) when the index is unavailable — never an
+ * error, unlike the old semantic_search tool.
+ */
+import type { ResolvedSearchMode, SearchMode } from "./types.js";
+export interface ModeResolution {
+    mode: ResolvedSearchMode;
+    /** Set when the resolved mode is a forced degradation of the request. */
+    degradedReason?: string;
+}
+/** Regex metacharacters or quoted strings — queries where exact matching is
+ *  clearly what the caller wants. Path-like queries deliberately do NOT
+ *  count: the eval gate showed them scoring 0% lexically (content grep
+ *  cannot find a file by its own name) and 100% in hybrid, where the
+ *  embedding side and the reranker's path-affinity signal carry them. */
+export declare function hasStrongLexicalSignals(query: string): boolean;
+export declare function resolveSearchMode(query: string, requested: SearchMode, embedAvailable: boolean, embedUnavailableReason?: string): ModeResolution;
+//# sourceMappingURL=mode.d.ts.map

package/dist/core/search/mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../../src/core/search/mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,kBAAkB,CAAC;IACzB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;yEAIyE;AACzE,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,UAAU,EACrB,cAAc,EAAE,OAAO,EACvB,sBAAsB,CAAC,EAAE,MAAM,GAC7B,cAAc,CAahB","sourcesContent":["/**\n * Availability-first search mode resolution\n * (docs/hybrid-retrieval-design.md, Decision 4).\n *\n * No clever query router: with a hot local daemon, running both retrievers\n * costs one extra embedding query, while misrouting costs recall. `auto`\n * therefore means hybrid whenever the index is available, dropping to lexical\n * only on strong lexical signals. Requested semantic/hybrid degrade to\n * lexical (with a recorded reason) when the index is unavailable — never an\n * error, unlike the old semantic_search tool.\n */\n\nimport type { ResolvedSearchMode, SearchMode } from \"./types.js\";\n\nexport interface ModeResolution {\n\tmode: ResolvedSearchMode;\n\t/** Set when the resolved mode is a forced degradation of the request. */\n\tdegradedReason?: string;\n}\n\n/** Regex metacharacters or quoted strings — queries where exact matching is\n *  clearly what the caller wants. Path-like queries deliberately do NOT\n *  count: the eval gate showed them scoring 0% lexically (content grep\n *  cannot find a file by its own name) and 100% in hybrid, where the\n *  embedding side and the reranker's path-affinity signal carry them. */\nexport function hasStrongLexicalSignals(query: string): boolean {\n\tif (/[\"'`]/.test(query)) return true;\n\tif (/[\\\\^$|()[\\]{}*+?]/.test(query)) return true;\n\treturn false;\n}\n\nexport function resolveSearchMode(\n\tquery: string,\n\trequested: SearchMode,\n\tembedAvailable: boolean,\n\tembedUnavailableReason?: string,\n): ModeResolution {\n\tif (requested === \"lexical\") return { mode: \"lexical\" };\n\n\tif (!embedAvailable) {\n\t\tconst reason = embedUnavailableReason ?? \"semantic index unavailable\";\n\t\treturn requested === \"auto\"\n\t\t\t? { mode: \"lexical\" }\n\t\t\t: { mode: \"lexical\", degradedReason: `${requested} requested but ${reason}` };\n\t}\n\n\tif (requested === \"semantic\" || requested === \"hybrid\") return { mode: requested };\n\n\treturn hasStrongLexicalSignals(query) ? { mode: \"lexical\" } : { mode: \"hybrid\" };\n}\n"]}

package/dist/core/search/mode.js

@@ -0,0 +1,37 @@
+/**
+ * Availability-first search mode resolution
+ * (docs/hybrid-retrieval-design.md, Decision 4).
+ *
+ * No clever query router: with a hot local daemon, running both retrievers
+ * costs one extra embedding query, while misrouting costs recall. `auto`
+ * therefore means hybrid whenever the index is available, dropping to lexical
+ * only on strong lexical signals. Requested semantic/hybrid degrade to
+ * lexical (with a recorded reason) when the index is unavailable — never an
+ * error, unlike the old semantic_search tool.
+ */
+/** Regex metacharacters or quoted strings — queries where exact matching is
+ *  clearly what the caller wants. Path-like queries deliberately do NOT
+ *  count: the eval gate showed them scoring 0% lexically (content grep
+ *  cannot find a file by its own name) and 100% in hybrid, where the
+ *  embedding side and the reranker's path-affinity signal carry them. */
+export function hasStrongLexicalSignals(query) {
+    if (/["'`]/.test(query))
+        return true;
+    if (/[\\^$|()[\]{}*+?]/.test(query))
+        return true;
+    return false;
+}
+export function resolveSearchMode(query, requested, embedAvailable, embedUnavailableReason) {
+    if (requested === "lexical")
+        return { mode: "lexical" };
+    if (!embedAvailable) {
+        const reason = embedUnavailableReason ?? "semantic index unavailable";
+        return requested === "auto"
+            ? { mode: "lexical" }
+            : { mode: "lexical", degradedReason: `${requested} requested but ${reason}` };
+    }
+    if (requested === "semantic" || requested === "hybrid")
+        return { mode: requested };
+    return hasStrongLexicalSignals(query) ? { mode: "lexical" } : { mode: "hybrid" };
+}
+//# sourceMappingURL=mode.js.map

package/dist/core/search/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../../src/core/search/mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH;;;;yEAIyE;AACzE,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAW;IAC/D,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,OAAO,KAAK,CAAC;AAAA,CACb;AAED,MAAM,UAAU,iBAAiB,CAChC,KAAa,EACb,SAAqB,EACrB,cAAuB,EACvB,sBAA+B,EACd;IACjB,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAExD,IAAI,CAAC,cAAc,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,sBAAsB,IAAI,4BAA4B,CAAC;QACtE,OAAO,SAAS,KAAK,MAAM;YAC1B,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;YACrB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,GAAG,SAAS,kBAAkB,MAAM,EAAE,EAAE,CAAC;IAChF,CAAC;IAED,IAAI,SAAS,KAAK,UAAU,IAAI,SAAS,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAEnF,OAAO,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAAA,CACjF","sourcesContent":["/**\n * Availability-first search mode resolution\n * (docs/hybrid-retrieval-design.md, Decision 4).\n *\n * No clever query router: with a hot local daemon, running both retrievers\n * costs one extra embedding query, while misrouting costs recall. `auto`\n * therefore means hybrid whenever the index is available, dropping to lexical\n * only on strong lexical signals. Requested semantic/hybrid degrade to\n * lexical (with a recorded reason) when the index is unavailable — never an\n * error, unlike the old semantic_search tool.\n */\n\nimport type { ResolvedSearchMode, SearchMode } from \"./types.js\";\n\nexport interface ModeResolution {\n\tmode: ResolvedSearchMode;\n\t/** Set when the resolved mode is a forced degradation of the request. */\n\tdegradedReason?: string;\n}\n\n/** Regex metacharacters or quoted strings — queries where exact matching is\n *  clearly what the caller wants. Path-like queries deliberately do NOT\n *  count: the eval gate showed them scoring 0% lexically (content grep\n *  cannot find a file by its own name) and 100% in hybrid, where the\n *  embedding side and the reranker's path-affinity signal carry them. */\nexport function hasStrongLexicalSignals(query: string): boolean {\n\tif (/[\"'`]/.test(query)) return true;\n\tif (/[\\\\^$|()[\\]{}*+?]/.test(query)) return true;\n\treturn false;\n}\n\nexport function resolveSearchMode(\n\tquery: string,\n\trequested: SearchMode,\n\tembedAvailable: boolean,\n\tembedUnavailableReason?: string,\n): ModeResolution {\n\tif (requested === \"lexical\") return { mode: \"lexical\" };\n\n\tif (!embedAvailable) {\n\t\tconst reason = embedUnavailableReason ?? \"semantic index unavailable\";\n\t\treturn requested === \"auto\"\n\t\t\t? { mode: \"lexical\" }\n\t\t\t: { mode: \"lexical\", degradedReason: `${requested} requested but ${reason}` };\n\t}\n\n\tif (requested === \"semantic\" || requested === \"hybrid\") return { mode: requested };\n\n\treturn hasStrongLexicalSignals(query) ? { mode: \"lexical\" } : { mode: \"hybrid\" };\n}\n"]}

package/dist/core/search/rerank.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Deterministic reranker over the fused top-50
+ * (docs/hybrid-retrieval-design.md, step 7 of the shipping order).
+ *
+ * The eval gate showed fused Recall@50 well above Recall@5/10 — the right
+ * candidates survive fusion but sit too deep. This reranker re-orders them
+ * using evidence that is only cheap to compute *after* fusion, when there
+ * are ≤50 candidates instead of thousands of lines:
+ *
+ *   - term coverage: how many distinct query terms appear in the candidate's
+ *     actual expanded window (read from disk);
+ *   - path affinity: query terms appearing in the candidate's file path —
+ *     this is what lets a query like `core/search/hybrid-search.ts` rank the
+ *     file itself first, which content grep alone cannot do;
+ *   - fused prior: the RRF ordering, so retriever consensus still counts.
+ *
+ * Purely lexical-statistical and deterministic — no model, no I/O beyond
+ * reading candidate windows. A cross-encoder can later replace the scoring
+ * function behind the same signature; that model work belongs to
+ * `kolisachint/embeddingsearchtools`, not here.
+ */
+import type { FusedCandidate } from "./types.js";
+export interface RerankResult {
+    candidates: FusedCandidate[];
+    latencyMs: number;
+}
+export declare function rerankCandidates(query: string, candidates: readonly FusedCandidate[], cwd: string): RerankResult;
+//# sourceMappingURL=rerank.d.ts.map

package/dist/core/search/rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.d.ts","sourceRoot":"","sources":["../../../src/core/search/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAYjD,MAAM,WAAW,YAAY;IAC5B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,cAAc,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAwDhH","sourcesContent":["/**\n * Deterministic reranker over the fused top-50\n * (docs/hybrid-retrieval-design.md, step 7 of the shipping order).\n *\n * The eval gate showed fused Recall@50 well above Recall@5/10 — the right\n * candidates survive fusion but sit too deep. This reranker re-orders them\n * using evidence that is only cheap to compute *after* fusion, when there\n * are ≤50 candidates instead of thousands of lines:\n *\n *   - term coverage: how many distinct query terms appear in the candidate's\n *     actual expanded window (read from disk);\n *   - path affinity: query terms appearing in the candidate's file path —\n *     this is what lets a query like `core/search/hybrid-search.ts` rank the\n *     file itself first, which content grep alone cannot do;\n *   - fused prior: the RRF ordering, so retriever consensus still counts.\n *\n * Purely lexical-statistical and deterministic — no model, no I/O beyond\n * reading candidate windows. A cross-encoder can later replace the scoring\n * function behind the same signature; that model work belongs to\n * `kolisachint/embeddingsearchtools`, not here.\n */\n\nimport { readFileSync } from \"fs\";\nimport path from \"path\";\nimport { buildLexicalQueryPlan } from \"./lexical-retriever.js\";\nimport type { FusedCandidate } from \"./types.js\";\n\n/** Weights of the scoring blend. The eval harness (scripts/search-eval.mjs)\n *  is the instrument for changing them — don't tune blind. */\nconst WEIGHT_FUSED_PRIOR = 0.4;\nconst WEIGHT_TERM_COVERAGE = 0.35;\nconst WEIGHT_PATH_AFFINITY = 0.25;\n/** Additive bonus when the query *is* the candidate's path (or its suffix):\n *  the caller named the file, so no amount of content evidence elsewhere\n *  should outrank it. */\nconst EXACT_PATH_BONUS = 0.5;\n\nexport interface RerankResult {\n\tcandidates: FusedCandidate[];\n\tlatencyMs: number;\n}\n\nexport function rerankCandidates(query: string, candidates: readonly FusedCandidate[], cwd: string): RerankResult {\n\tconst startedMs = Date.now();\n\tconst plan = buildLexicalQueryPlan(query);\n\tif (!plan || candidates.length < 2) {\n\t\treturn { candidates: [...candidates], latencyMs: Date.now() - startedMs };\n\t}\n\tconst terms = plan.terms;\n\tconst queryPath = query.trim().toLowerCase();\n\n\tconst fileCache = new Map<string, string[] | undefined>();\n\tconst readLines = (rel: string): string[] | undefined => {\n\t\tif (!fileCache.has(rel)) {\n\t\t\ttry {\n\t\t\t\tconst content = readFileSync(path.resolve(cwd, rel), \"utf-8\");\n\t\t\t\tfileCache.set(rel, content.toLowerCase().split(\"\\n\"));\n\t\t\t} catch {\n\t\t\t\tfileCache.set(rel, undefined);\n\t\t\t}\n\t\t}\n\t\treturn fileCache.get(rel);\n\t};\n\n\tconst scored = candidates.map((candidate, index) => {\n\t\t// Fused prior: normalized RRF ordering, 1 for the top candidate.\n\t\tconst fusedPrior = 1 - index / candidates.length;\n\n\t\tconst lines = readLines(candidate.path);\n\t\tlet termCoverage = 0;\n\t\tif (lines && terms.length > 0) {\n\t\t\tconst window = lines\n\t\t\t\t.slice(Math.max(0, candidate.startLine - 1), Math.min(lines.length, candidate.endLine))\n\t\t\t\t.join(\"\\n\");\n\t\t\ttermCoverage = terms.filter((t) => window.includes(t)).length / terms.length;\n\t\t}\n\n\t\tconst lowerPath = candidate.path.toLowerCase();\n\t\t// A quoted phrase rarely names a file; split it into path-ish tokens so\n\t\t// `\"token budget exceeded\"` still gets partial path credit.\n\t\tconst pathTerms = terms.length === 1 ? terms[0].split(/[^a-z0-9_$]+/).filter((t) => t.length >= 3) : terms;\n\t\tconst pathAffinity =\n\t\t\tpathTerms.length > 0 ? pathTerms.filter((t) => lowerPath.includes(t)).length / pathTerms.length : 0;\n\n\t\tconst exactPath =\n\t\t\tqueryPath.length >= 3 && (lowerPath === queryPath || lowerPath.endsWith(`/${queryPath}`)) ? 1 : 0;\n\n\t\tconst score =\n\t\t\tWEIGHT_FUSED_PRIOR * fusedPrior +\n\t\t\tWEIGHT_TERM_COVERAGE * termCoverage +\n\t\t\tWEIGHT_PATH_AFFINITY * pathAffinity +\n\t\t\tEXACT_PATH_BONUS * exactPath;\n\t\treturn { candidate, index, score };\n\t});\n\n\t// Stable, deterministic: score desc, fused order as tie-break.\n\tscored.sort((a, b) => b.score - a.score || a.index - b.index);\n\treturn { candidates: scored.map((s) => s.candidate), latencyMs: Date.now() - startedMs };\n}\n"]}

package/dist/core/search/rerank.js

@@ -0,0 +1,82 @@
+/**
+ * Deterministic reranker over the fused top-50
+ * (docs/hybrid-retrieval-design.md, step 7 of the shipping order).
+ *
+ * The eval gate showed fused Recall@50 well above Recall@5/10 — the right
+ * candidates survive fusion but sit too deep. This reranker re-orders them
+ * using evidence that is only cheap to compute *after* fusion, when there
+ * are ≤50 candidates instead of thousands of lines:
+ *
+ *   - term coverage: how many distinct query terms appear in the candidate's
+ *     actual expanded window (read from disk);
+ *   - path affinity: query terms appearing in the candidate's file path —
+ *     this is what lets a query like `core/search/hybrid-search.ts` rank the
+ *     file itself first, which content grep alone cannot do;
+ *   - fused prior: the RRF ordering, so retriever consensus still counts.
+ *
+ * Purely lexical-statistical and deterministic — no model, no I/O beyond
+ * reading candidate windows. A cross-encoder can later replace the scoring
+ * function behind the same signature; that model work belongs to
+ * `kolisachint/embeddingsearchtools`, not here.
+ */
+import { readFileSync } from "fs";
+import path from "path";
+import { buildLexicalQueryPlan } from "./lexical-retriever.js";
+/** Weights of the scoring blend. The eval harness (scripts/search-eval.mjs)
+ *  is the instrument for changing them — don't tune blind. */
+const WEIGHT_FUSED_PRIOR = 0.4;
+const WEIGHT_TERM_COVERAGE = 0.35;
+const WEIGHT_PATH_AFFINITY = 0.25;
+/** Additive bonus when the query *is* the candidate's path (or its suffix):
+ *  the caller named the file, so no amount of content evidence elsewhere
+ *  should outrank it. */
+const EXACT_PATH_BONUS = 0.5;
+export function rerankCandidates(query, candidates, cwd) {
+    const startedMs = Date.now();
+    const plan = buildLexicalQueryPlan(query);
+    if (!plan || candidates.length < 2) {
+        return { candidates: [...candidates], latencyMs: Date.now() - startedMs };
+    }
+    const terms = plan.terms;
+    const queryPath = query.trim().toLowerCase();
+    const fileCache = new Map();
+    const readLines = (rel) => {
+        if (!fileCache.has(rel)) {
+            try {
+                const content = readFileSync(path.resolve(cwd, rel), "utf-8");
+                fileCache.set(rel, content.toLowerCase().split("\n"));
+            }
+            catch {
+                fileCache.set(rel, undefined);
+            }
+        }
+        return fileCache.get(rel);
+    };
+    const scored = candidates.map((candidate, index) => {
+        // Fused prior: normalized RRF ordering, 1 for the top candidate.
+        const fusedPrior = 1 - index / candidates.length;
+        const lines = readLines(candidate.path);
+        let termCoverage = 0;
+        if (lines && terms.length > 0) {
+            const window = lines
+                .slice(Math.max(0, candidate.startLine - 1), Math.min(lines.length, candidate.endLine))
+                .join("\n");
+            termCoverage = terms.filter((t) => window.includes(t)).length / terms.length;
+        }
+        const lowerPath = candidate.path.toLowerCase();
+        // A quoted phrase rarely names a file; split it into path-ish tokens so
+        // `"token budget exceeded"` still gets partial path credit.
+        const pathTerms = terms.length === 1 ? terms[0].split(/[^a-z0-9_$]+/).filter((t) => t.length >= 3) : terms;
+        const pathAffinity = pathTerms.length > 0 ? pathTerms.filter((t) => lowerPath.includes(t)).length / pathTerms.length : 0;
+        const exactPath = queryPath.length >= 3 && (lowerPath === queryPath || lowerPath.endsWith(`/${queryPath}`)) ? 1 : 0;
+        const score = WEIGHT_FUSED_PRIOR * fusedPrior +
+            WEIGHT_TERM_COVERAGE * termCoverage +
+            WEIGHT_PATH_AFFINITY * pathAffinity +
+            EXACT_PATH_BONUS * exactPath;
+        return { candidate, index, score };
+    });
+    // Stable, deterministic: score desc, fused order as tie-break.
+    scored.sort((a, b) => b.score - a.score || a.index - b.index);
+    return { candidates: scored.map((s) => s.candidate), latencyMs: Date.now() - startedMs };
+}
+//# sourceMappingURL=rerank.js.map