ragcode-context-engine 0.1.0

package/dist/src/mcp/tools.js

@@ -0,0 +1,309 @@
+import { z } from "zod";
+import { buildExplainImpactReport } from "../subgraph/impact-explainer.js";
+import { expandNode, parseNodeRef } from "../subgraph/node-expander.js";
+import { applyExplainImpactOutputPreset, applySubgraphOutputPreset } from "../subgraph/output-preset.js";
+import { readWatcherLiveness } from "../watch/watcher-liveness.js";
+export const ToolNameSchema = z.enum([
+    "index_repo",
+    "refresh_index",
+    "index_status",
+    "watch_status",
+    "record_file_events",
+    "search_code",
+    "get_context",
+    "topology_map",
+    "find_symbol",
+    "explain_file",
+    "expand_node",
+    "find_owner",
+    "find_reuse_candidates",
+    "impact_analysis",
+    "explain_impact",
+    "related_tests",
+    "trace_flow",
+    "trace_request_flow",
+    "review_diff"
+]);
+export const IndexRepoInput = z.object({ repoRoot: z.string().min(1) });
+export const ContextModeSchema = z.enum(["auto", "debug", "feature", "refactor", "review", "explain"]);
+export const ExpansionLevelSchema = z.enum(["file_card", "skeleton", "focused_body", "full_body"]);
+export const SubgraphOutputPresetSchema = z.enum(["compact", "agent_edit", "debug_trace", "review_risk"]);
+export const WorkspaceHintInput = z.object({ root: z.string().min(1).optional(), filePath: z.string().min(1).optional() }).optional();
+export const RefreshIndexInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput });
+export const IndexStatusInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput });
+export const WatchStatusInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput });
+export const RecordFileEventsInput = z.object({
+    repoRoot: z.string().min(1).optional(),
+    workspace: WorkspaceHintInput,
+    filePaths: z.array(z.string().min(1)).min(1),
+    burstThreshold: z.number().int().positive().optional(),
+    maxDirtyFiles: z.number().int().positive().optional()
+});
+export const SearchCodeInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput, query: z.string().min(1), limit: z.number().int().positive().optional(), mode: ContextModeSchema.optional() });
+export const GetContextInput = SearchCodeInput.extend({ budgetChars: z.number().int().positive().optional() });
+export const TopologyMapInput = SearchCodeInput.extend({ budgetChars: z.number().int().positive().optional(), maxEdges: z.number().int().positive().optional() });
+export const FindSymbolInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput, name: z.string().min(1) });
+export const ExplainFileInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput, filePath: z.string().min(1) });
+export const ExpandNodeInput = z.object({
+    repoRoot: z.string().min(1).optional(),
+    workspace: WorkspaceHintInput,
+    nodeRef: z.string().min(1),
+    expansionLevel: ExpansionLevelSchema.optional(),
+    budgetChars: z.number().int().positive().optional()
+});
+export const FindOwnerInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput, query: z.string().min(1), limit: z.number().int().positive().optional() });
+export const FindReuseCandidatesInput = FindOwnerInput.extend({ reuseGuard: z.boolean().optional() });
+export const ImpactAnalysisInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput, target: z.string().min(1) });
+export const ExplainImpactInput = ImpactAnalysisInput.extend({ budgetChars: z.number().int().positive().optional(), maxHops: z.number().int().positive().optional(), preset: SubgraphOutputPresetSchema.optional() });
+export const RelatedTestsInput = ImpactAnalysisInput;
+export const TraceFlowInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput, entry: z.string().min(1), maxSteps: z.number().int().positive().optional() });
+export const TraceRequestFlowInput = z.object({
+    repoRoot: z.string().min(1).optional(),
+    workspace: WorkspaceHintInput,
+    entry: z.string().min(1),
+    query: z.string().min(1).optional(),
+    budgetChars: z.number().int().positive().optional(),
+    maxHops: z.number().int().positive().optional(),
+    preset: SubgraphOutputPresetSchema.optional()
+});
+export const ReviewDiffInput = z.object({ repoRoot: z.string().min(1).optional(), workspace: WorkspaceHintInput, diff: z.string().optional(), changedFiles: z.array(z.string()).optional() });
+export function listToolDefinitions() {
+    return listRuntimeToolDefinitions().map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: zodToJsonShape(tool.inputSchema)
+    }));
+}
+export function listRuntimeToolDefinitions() {
+    return [
+        {
+            name: "index_repo",
+            description: "Index or re-index a local repository into the structural graph and semantic store.",
+            inputSchema: IndexRepoInput
+        },
+        {
+            name: "refresh_index",
+            description: "Force refresh the active indexed repository. Currently performs a full reindex; future versions can narrow to changed files.",
+            inputSchema: RefreshIndexInput
+        },
+        {
+            name: "index_status",
+            description: "Report indexed file/chunk/symbol/edge counts plus freshness, stale, pending, and skipped file state for the active repository.",
+            inputSchema: IndexStatusInput
+        },
+        {
+            name: "watch_status",
+            description: "Report whether a background watcher is alive for the active repository (lock + heartbeat liveness) plus current dirty/pending backlog. Read-only: never starts a watcher.",
+            inputSchema: WatchStatusInput
+        },
+        {
+            name: "record_file_events",
+            description: "Record watcher file events as coalesced dirty-file state without indexing immediately.",
+            inputSchema: RecordFileEventsInput
+        },
+        {
+            name: "search_code",
+            description: "Run hybrid code search over keyword and semantic indexes.",
+            inputSchema: SearchCodeInput
+        },
+        {
+            name: "get_context",
+            description: "Build an agent-ready context pack for a code question under a character budget.",
+            inputSchema: GetContextInput
+        },
+        {
+            name: "topology_map",
+            description: "Return owner-chain and topology edges for a feature/domain query without full evidence snippets.",
+            inputSchema: TopologyMapInput
+        },
+        {
+            name: "find_symbol",
+            description: "Find indexed symbols by name.",
+            inputSchema: FindSymbolInput
+        },
+        {
+            name: "explain_file",
+            description: "Return indexed file metadata, chunks, and symbols for a file.",
+            inputSchema: ExplainFileInput
+        },
+        {
+            name: "expand_node",
+            description: "Expand one node from a compact subgraph as a focused body, skeleton, file card, or full body under budget.",
+            inputSchema: ExpandNodeInput
+        },
+        {
+            name: "find_owner",
+            description: "Find likely owner files and symbols for a feature, bug, or architecture question.",
+            inputSchema: FindOwnerInput
+        },
+        {
+            name: "find_reuse_candidates",
+            description: "Find existing helpers, services, hooks, components, wrappers, schemas, or fixtures that should be reused before writing new code.",
+            inputSchema: FindReuseCandidatesInput
+        },
+        {
+            name: "impact_analysis",
+            description: "Estimate direct structural impact for a file or symbol using graph edges.",
+            inputSchema: ImpactAnalysisInput
+        },
+        {
+            name: "explain_impact",
+            description: "Return a verified minimal blast-radius subgraph with coverage signals, risk score, and edit-readiness guidance.",
+            inputSchema: ExplainImpactInput
+        },
+        {
+            name: "related_tests",
+            description: "Find likely related test files for a file or symbol target.",
+            inputSchema: RelatedTestsInput
+        },
+        {
+            name: "trace_flow",
+            description: "Trace outgoing call edges from an entry symbol or file hint.",
+            inputSchema: TraceFlowInput
+        },
+        {
+            name: "trace_request_flow",
+            description: "Return an ordered verified request/data-flow subgraph from an entry symbol or file hint.",
+            inputSchema: TraceRequestFlowInput
+        },
+        {
+            name: "review_diff",
+            description: "Review changed files or a unified diff for risk and related tests.",
+            inputSchema: ReviewDiffInput
+        }
+    ];
+}
+export async function callTool(engine, name, rawInput) {
+    switch (name) {
+        case "index_repo": {
+            const input = IndexRepoInput.parse(rawInput);
+            return engine.indexRepo(input.repoRoot);
+        }
+        case "refresh_index": {
+            const input = RefreshIndexInput.parse(rawInput);
+            return engine.refreshIndex(input.repoRoot ?? input.workspace?.root);
+        }
+        case "index_status": {
+            const input = IndexStatusInput.parse(rawInput);
+            return engine.indexStatus(input.repoRoot ?? input.workspace?.root);
+        }
+        case "watch_status": {
+            const input = WatchStatusInput.parse(rawInput);
+            // Resolve the repo via indexStatus (which applies workspace resolution), then read liveness
+            // from the on-disk lock/heartbeat. Pure read — never spawns a watcher; clients that want one
+            // running must install the OS service (`ragcode service install`) or run `ragcode watch`.
+            const status = await engine.indexStatus(input.repoRoot ?? input.workspace?.root);
+            const liveness = await readWatcherLiveness(status.repoRoot);
+            return {
+                repoRoot: status.repoRoot,
+                projectId: status.projectId,
+                watcher: liveness,
+                backlog: {
+                    pendingFiles: status.pendingFileCount,
+                    indexingFiles: status.indexingFileCount,
+                    staleFiles: status.staleFileCount
+                },
+                hint: liveness.state === "running"
+                    ? undefined
+                    : "No live watcher; the index will not auto-refresh. Run `ragcode service install <repo>` for a background watcher, or `ragcode watch <repo>` manually."
+            };
+        }
+        case "record_file_events": {
+            const input = RecordFileEventsInput.parse(rawInput);
+            return engine.recordFileEvents(input.repoRoot ?? input.workspace?.root, input.filePaths, {
+                burstThreshold: input.burstThreshold,
+                maxDirtyFiles: input.maxDirtyFiles
+            });
+        }
+        case "search_code": {
+            const input = SearchCodeInput.parse(rawInput);
+            return engine.searchCode(input);
+        }
+        case "get_context": {
+            const input = GetContextInput.parse(rawInput);
+            return engine.getContext(input);
+        }
+        case "topology_map": {
+            const input = TopologyMapInput.parse(rawInput);
+            return engine.topologyMap(input);
+        }
+        case "find_symbol": {
+            const input = FindSymbolInput.parse(rawInput);
+            return engine.findSymbol(input.repoRoot ?? input.workspace?.root, input.name);
+        }
+        case "explain_file": {
+            const input = ExplainFileInput.parse(rawInput);
+            return engine.explainFile(input.repoRoot ?? input.workspace?.root, input.filePath);
+        }
+        case "expand_node": {
+            const input = ExpandNodeInput.parse(rawInput);
+            const parsed = parseNodeRef(input.nodeRef);
+            const indexedFile = await engine.explainFile(input.repoRoot ?? input.workspace?.root, parsed.filePath);
+            return expandNode({
+                nodeRef: input.nodeRef,
+                chunks: indexedFile.chunks,
+                symbols: indexedFile.symbols,
+                expansionLevel: input.expansionLevel,
+                budgetChars: input.budgetChars
+            });
+        }
+        case "find_owner": {
+            const input = FindOwnerInput.parse(rawInput);
+            return engine.findOwner(input.repoRoot ?? input.workspace?.root, input.query, input.limit);
+        }
+        case "find_reuse_candidates": {
+            const input = FindReuseCandidatesInput.parse(rawInput);
+            return engine.findReuseCandidates(input);
+        }
+        case "impact_analysis": {
+            const input = ImpactAnalysisInput.parse(rawInput);
+            return engine.impactAnalysis(input.repoRoot ?? input.workspace?.root, input.target);
+        }
+        case "explain_impact": {
+            const input = ExplainImpactInput.parse(rawInput);
+            const subgraph = await engine.verifiedSubgraph({
+                repoRoot: input.repoRoot ?? input.workspace?.root,
+                workspace: input.workspace,
+                query: input.target,
+                seed: input.target,
+                mode: "impact",
+                budgetChars: input.budgetChars,
+                maxHops: input.maxHops
+            });
+            return applyExplainImpactOutputPreset(buildExplainImpactReport(input.target, subgraph), input.preset ?? "compact");
+        }
+        case "related_tests": {
+            const input = RelatedTestsInput.parse(rawInput);
+            return engine.relatedTests(input.repoRoot ?? input.workspace?.root, input.target);
+        }
+        case "trace_flow": {
+            const input = TraceFlowInput.parse(rawInput);
+            return engine.traceFlow(input.repoRoot ?? input.workspace?.root, input.entry, input.maxSteps);
+        }
+        case "trace_request_flow": {
+            const input = TraceRequestFlowInput.parse(rawInput);
+            const subgraph = await engine.verifiedSubgraph({
+                repoRoot: input.repoRoot ?? input.workspace?.root,
+                workspace: input.workspace,
+                query: input.query ?? input.entry,
+                seed: input.entry,
+                mode: "flow",
+                budgetChars: input.budgetChars,
+                maxHops: input.maxHops
+            });
+            return applySubgraphOutputPreset(subgraph, input.preset ?? "compact");
+        }
+        case "review_diff": {
+            const input = ReviewDiffInput.parse(rawInput);
+            return engine.reviewDiff(input.repoRoot ?? input.workspace?.root, input.diff, input.changedFiles);
+        }
+    }
+}
+function zodToJsonShape(schema) {
+    // Keep this intentionally lightweight for the foundation. The SDK server can
+    // later use zod directly; this shape is enough for docs/tests/tool listing.
+    return {
+        type: "object",
+        description: schema.description ?? "See tool input contract in src/mcp/tools.ts"
+    };
+}

package/dist/src/project/project-identity.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectIdentity } from "../core/types.js";
+export declare function createProjectIdentity(repoRoot: string): Promise<ProjectIdentity>;

package/dist/src/project/project-identity.js

@@ -0,0 +1,24 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { sha256 } from "../utils/hash.js";
+export async function createProjectIdentity(repoRoot) {
+    const resolvedRoot = path.resolve(repoRoot);
+    const canonicalRoot = await fs.realpath(resolvedRoot).catch(() => resolvedRoot);
+    const gitRemote = await readGitRemote(canonicalRoot);
+    return {
+        projectId: sha256([canonicalRoot.toLowerCase(), gitRemote ?? ""].join("::")).slice(0, 24),
+        repoRoot: resolvedRoot,
+        canonicalRoot,
+        displayName: path.basename(canonicalRoot),
+        gitRemote,
+        createdAtMs: Date.now()
+    };
+}
+async function readGitRemote(repoRoot) {
+    const configPath = path.join(repoRoot, ".git", "config");
+    const config = await fs.readFile(configPath, "utf8").catch(() => undefined);
+    if (!config)
+        return undefined;
+    const match = /\[remote "origin"\][\s\S]*?url\s*=\s*(.+)/.exec(config);
+    return match?.[1]?.trim();
+}

package/dist/src/project/project-registry.d.ts

@@ -0,0 +1,12 @@
+import type { ProjectIdentity } from "../core/types.js";
+export declare class ProjectRegistry {
+    private readonly byId;
+    private readonly byRoot;
+    register(repoRoot: string): Promise<ProjectIdentity>;
+    upsert(project: ProjectIdentity): ProjectIdentity;
+    getByProjectId(projectId: string): ProjectIdentity | undefined;
+    findByRoot(root: string): ProjectIdentity | undefined;
+    findContainingPath(filePath: string): ProjectIdentity[];
+    list(): ProjectIdentity[];
+}
+export declare function isInside(root: string, candidate: string): boolean;

package/dist/src/project/project-registry.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { createProjectIdentity } from "./project-identity.js";
+export class ProjectRegistry {
+    byId = new Map();
+    byRoot = new Map();
+    async register(repoRoot) {
+        const identity = await createProjectIdentity(repoRoot);
+        const existing = this.byId.get(identity.projectId);
+        const merged = {
+            ...(existing ?? identity),
+            ...identity,
+            createdAtMs: existing?.createdAtMs ?? identity.createdAtMs,
+            lastIndexedAtMs: Date.now()
+        };
+        return this.upsert(merged);
+    }
+    upsert(project) {
+        const existing = this.byId.get(project.projectId);
+        const merged = {
+            ...(existing ?? project),
+            ...project,
+            createdAtMs: existing?.createdAtMs ?? project.createdAtMs
+        };
+        this.byId.set(merged.projectId, merged);
+        this.byRoot.set(normalizeRoot(merged.repoRoot), merged);
+        this.byRoot.set(normalizeRoot(merged.canonicalRoot), merged);
+        return merged;
+    }
+    getByProjectId(projectId) {
+        return this.byId.get(projectId);
+    }
+    findByRoot(root) {
+        return this.byRoot.get(normalizeRoot(root));
+    }
+    findContainingPath(filePath) {
+        const absolute = path.resolve(filePath);
+        return [...this.byId.values()].filter((project) => isInside(project.canonicalRoot, absolute) || isInside(project.repoRoot, absolute));
+    }
+    list() {
+        return [...this.byId.values()].sort((a, b) => a.canonicalRoot.localeCompare(b.canonicalRoot));
+    }
+}
+export function isInside(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function normalizeRoot(root) {
+    return path.resolve(root).toLowerCase();
+}

package/dist/src/project/workspace-resolver.d.ts

@@ -0,0 +1,20 @@
+import type { ProjectIdentity, WorkspaceHint, WorkspaceSession } from "../core/types.js";
+import { ProjectRegistry } from "./project-registry.js";
+export interface WorkspaceResolverOptions {
+    cwd?: string;
+    roots?: string[];
+}
+export declare class WorkspaceResolver {
+    private readonly registry;
+    private readonly options;
+    private active?;
+    constructor(registry: ProjectRegistry, options?: WorkspaceResolverOptions);
+    setActive(project: ProjectIdentity, resolvedFrom?: WorkspaceSession["resolvedFrom"]): WorkspaceSession;
+    resolve(input?: {
+        repoRoot?: string;
+        workspace?: WorkspaceHint;
+    }): WorkspaceSession;
+    getActive(): WorkspaceSession | undefined;
+    private fromFilePath;
+    private fromRoot;
+}

package/dist/src/project/workspace-resolver.js

@@ -0,0 +1,62 @@
+import path from "node:path";
+export class WorkspaceResolver {
+    registry;
+    options;
+    active;
+    constructor(registry, options = {}) {
+        this.registry = registry;
+        this.options = options;
+    }
+    setActive(project, resolvedFrom = "active_session") {
+        this.active = {
+            activeProjectId: project.projectId,
+            activeRepoRoot: project.repoRoot,
+            knownProjects: this.registry.list(),
+            resolvedFrom
+        };
+        return this.active;
+    }
+    resolve(input = {}) {
+        if (input.workspace?.filePath)
+            return this.fromFilePath(input.workspace.filePath);
+        if (input.workspace?.root)
+            return this.fromRoot(input.workspace.root, "root");
+        if (input.repoRoot)
+            return this.fromRoot(input.repoRoot, "repoRoot");
+        for (const root of this.options.roots ?? []) {
+            const project = this.registry.findByRoot(root);
+            if (project)
+                return this.setActive(project, "mcp_roots");
+        }
+        if (this.active)
+            return this.active;
+        if (this.options.cwd) {
+            const project = this.registry.findByRoot(this.options.cwd);
+            if (project)
+                return this.setActive(project, "cwd");
+        }
+        const projects = this.registry.list();
+        if (projects.length === 1)
+            return this.setActive(projects[0], "single_project");
+        if (projects.length > 1)
+            throw new Error(`Ambiguous workspace: ${projects.length} indexed projects are available. Provide workspace.root or workspace.filePath.`);
+        throw new Error("Missing workspace: index a repository or provide workspace.root before retrieval.");
+    }
+    getActive() {
+        return this.active;
+    }
+    fromFilePath(filePath) {
+        const matches = this.registry.findContainingPath(path.resolve(filePath));
+        if (matches.length === 1)
+            return this.setActive(matches[0], "filePath");
+        if (matches.length > 1)
+            throw new Error(`Ambiguous workspace for filePath: ${filePath}`);
+        throw new Error(`No indexed workspace contains filePath: ${filePath}`);
+    }
+    fromRoot(root, resolvedFrom) {
+        const project = this.registry.findByRoot(root);
+        if (!project)
+            throw new Error(`Workspace is not indexed: ${root}`);
+        return this.setActive(project, resolvedFrom);
+    }
+}

package/dist/src/retrieval/graph-reranker.d.ts

@@ -0,0 +1,11 @@
+import type { GraphStore } from "../core/contracts.js";
+import type { SearchHit, SearchQuery } from "../core/types.js";
+import type { ResolvedContextMode } from "./query-planner.js";
+export interface GraphRerankerOptions {
+    graphStore: GraphStore;
+    maxHops?: number;
+    maxSeeds?: number;
+    maxExpansionCandidates?: number;
+    maxExpansionHops?: number;
+}
+export declare function rerankWithGraph(hits: SearchHit[], query: SearchQuery, mode: ResolvedContextMode, options: GraphRerankerOptions): Promise<SearchHit[]>;

package/dist/src/retrieval/hybrid-retriever.d.ts

@@ -0,0 +1,31 @@
+import type { EmbeddingProvider, GraphStore, SemanticStore } from "../core/contracts.js";
+import type { SearchHit, SearchQuery } from "../core/types.js";
+export interface HybridRetrieverOptions {
+    graphStore: GraphStore;
+    semanticStore: SemanticStore;
+    embeddingProvider: EmbeddingProvider;
+}
+export interface HybridSearchDiagnostics {
+    keywordHitCount: number;
+    semantic: {
+        status: "ok" | "failed";
+        hitCount: number;
+        error?: string;
+    };
+    fusion: {
+        semanticTopNParticipation: number;
+    };
+}
+export interface HybridSearchResult {
+    hits: SearchHit[];
+    diagnostics: HybridSearchDiagnostics;
+}
+export declare class HybridRetriever {
+    private readonly options;
+    constructor(options: HybridRetrieverOptions);
+    search(query: SearchQuery): Promise<SearchHit[]>;
+    searchWithDiagnostics(query: SearchQuery): Promise<HybridSearchResult>;
+    private searchSemantic;
+}
+export declare function fuseHits(keywordHits: SearchHit[], semanticHits: SearchHit[]): SearchHit[];
+export declare function hasSemanticParticipation(hit: SearchHit): boolean;

package/dist/src/retrieval/hybrid-retriever.js

@@ -0,0 +1,111 @@
+import { rerankWithGraph } from "./graph-reranker.js";
+import { applyModeBoost, resolveContextMode } from "./query-planner.js";
+export class HybridRetriever {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async search(query) {
+        return (await this.searchWithDiagnostics(query)).hits;
+    }
+    async searchWithDiagnostics(query) {
+        const limit = query.limit ?? 20;
+        const keywordHits = await this.options.graphStore.searchText({ ...query, limit: limit * 2 });
+        const semanticResult = await this.searchSemantic({ ...query, limit: limit * 2 });
+        const mode = resolveContextMode(query.query, query.mode);
+        const fused = fuseHits(keywordHits, semanticResult.hits).map((hit) => applyModeBoost(hit, mode, query.query));
+        const reranked = await rerankWithGraph(fused, query, mode, { graphStore: this.options.graphStore });
+        const hits = reranked.filter((hit) => hit.score > 0).slice(0, limit);
+        return {
+            hits,
+            diagnostics: {
+                keywordHitCount: keywordHits.length,
+                semantic: {
+                    status: semanticResult.error ? "failed" : "ok",
+                    hitCount: semanticResult.hits.length,
+                    error: semanticResult.error
+                },
+                fusion: {
+                    semanticTopNParticipation: hits.filter(hasSemanticParticipation).length
+                }
+            }
+        };
+    }
+    async searchSemantic(query) {
+        try {
+            return { hits: await this.options.semanticStore.search(query, this.options.embeddingProvider) };
+        }
+        catch (error) {
+            return { hits: [], error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}
+export function fuseHits(keywordHits, semanticHits) {
+    const byChunk = new Map();
+    for (const hit of rankFusionHits(keywordHits, "keyword")) {
+        mergeHit(byChunk, hit);
+    }
+    for (const hit of rankFusionHits(semanticHits, "semantic")) {
+        mergeHit(byChunk, hit);
+    }
+    return [...byChunk.values()].sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.chunk.filePath.localeCompare(b.chunk.filePath);
+    });
+}
+export function hasSemanticParticipation(hit) {
+    return hit.source === "semantic" || /\bsemantic\b|vector similarity/i.test(hit.reason);
+}
+// Reciprocal Rank Fusion (Cormack et al. 2009). Fusion depends only on each
+// hit's rank within its own source list, not on raw score magnitude — this is
+// what lets us combine keyword (bm25, ~thousands) and semantic (cosine, 0..1)
+// scores that live on incompatible scales.
+//
+// Textbook RRF is 1/(k+rank), which tops out around 1/k (~0.016 at k=60) —
+// two orders of magnitude below the downstream modeBoost (~0.2-0.65) and
+// graphAdjustment (~0.15-2.5) that get *added* to the fused score later. To
+// keep the fused score on the same ~0..1 scale those boosts were tuned
+// against, we use the order-preserving variant k/(k+rank), which tops out near
+// 1.0. Scaling by a constant is monotonic, so it does not change RRF ranking.
+const RRF_K = 60;
+function rankFusionHits(hits, label) {
+    return hits.map((hit, index) => {
+        const rank = index + 1;
+        const score = RRF_K / (RRF_K + rank);
+        return {
+            ...hit,
+            score,
+            scoreBreakdown: {
+                ...hit.scoreBreakdown,
+                [label]: hit.score,
+                sourceNormalized: score,
+                final: score
+            },
+            reason: `${hit.reason}; rank fusion ${label} rank ${rank} rrf=${score.toFixed(3)}`
+        };
+    });
+}
+function mergeHit(byChunk, hit) {
+    const existing = byChunk.get(hit.chunk.id);
+    if (!existing) {
+        byChunk.set(hit.chunk.id, hit);
+        return;
+    }
+    byChunk.set(hit.chunk.id, {
+        ...existing,
+        score: existing.score + hit.score,
+        scoreBreakdown: {
+            ...existing.scoreBreakdown,
+            ...hit.scoreBreakdown,
+            keyword: existing.scoreBreakdown?.keyword ?? hit.scoreBreakdown?.keyword,
+            semantic: existing.scoreBreakdown?.semantic ?? hit.scoreBreakdown?.semantic,
+            sourceNormalized: (existing.scoreBreakdown?.sourceNormalized ?? existing.score) + (hit.scoreBreakdown?.sourceNormalized ?? hit.score),
+            modeBoost: (existing.scoreBreakdown?.modeBoost ?? 0) + (hit.scoreBreakdown?.modeBoost ?? 0),
+            graphAdjustment: (existing.scoreBreakdown?.graphAdjustment ?? 0) + (hit.scoreBreakdown?.graphAdjustment ?? 0),
+            final: existing.score + hit.score
+        },
+        source: existing.source === hit.source ? existing.source : "graph",
+        reason: `${existing.reason}; ${hit.reason}`
+    });
+}

package/dist/src/retrieval/path-classification.d.ts

@@ -0,0 +1,6 @@
+export type EvidencePathKind = "implementation" | "test" | "docs" | "fixture";
+export declare function classifyEvidencePath(filePath: string): EvidencePathKind;
+export declare function isSupportingEvidencePath(filePath: string): boolean;
+export declare function isExplicitSupportingEvidenceQuery(query: string): boolean;
+export declare function isExplicitTestQuery(query: string): boolean;
+export declare function isTestPath(filePath: string): boolean;

package/dist/src/retrieval/path-classification.js

@@ -0,0 +1,22 @@
+export function classifyEvidencePath(filePath) {
+    const normalized = filePath.replaceAll("\\", "/").toLowerCase();
+    if (isTestPath(normalized))
+        return "test";
+    if (/(^|\/)(__fixtures__|fixtures?|playground|examples?|samples?|demo)(\/|$)/.test(normalized))
+        return "fixture";
+    if (/(^|\/)(docs?|documentation)(\/|$)|\.mdx?$/.test(normalized))
+        return "docs";
+    return "implementation";
+}
+export function isSupportingEvidencePath(filePath) {
+    return classifyEvidencePath(filePath) !== "implementation";
+}
+export function isExplicitSupportingEvidenceQuery(query) {
+    return /\b(test|tests|spec|coverage|regression|doc|docs|documentation|readme|example|examples|sample|samples|fixture|fixtures|playground|demo)\b/i.test(query);
+}
+export function isExplicitTestQuery(query) {
+    return /\b(test|tests|spec|coverage|regression)\b/i.test(query);
+}
+export function isTestPath(filePath) {
+    return /(^|\/)(__tests__|tests?)(\/|$)|\.(test|spec)\.[jt]sx?$/.test(filePath.replaceAll("\\", "/").toLowerCase());
+}