codesearch-mcp 0.2.3-alpha → 0.4.0-alpha

package/dist/src/search/ChunkSearch.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChunkSearch = void 0;
+const result_shaping_1 = require("./result-shaping");
+const search_plan_1 = require("./chunks/search-plan");
+const IterativeScanGate_1 = require("./chunks/IterativeScanGate");
+const CandidateFetcher_1 = require("./chunks/CandidateFetcher");
+const RerankStage_1 = require("./chunks/RerankStage");
+const search_metrics_1 = require("./chunks/search-metrics");
+class ChunkSearch {
+    db;
+    embedder;
+    identityGuard;
+    config;
+    logger;
+    gate;
+    fetcher;
+    rerankStage;
+    constructor(db, embedder, identityGuard, config, logger) {
+        this.db = db;
+        this.embedder = embedder;
+        this.identityGuard = identityGuard;
+        this.config = config;
+        this.logger = logger;
+        this.gate = new IterativeScanGate_1.IterativeScanGate(db, logger);
+        this.fetcher = new CandidateFetcher_1.CandidateFetcher(db, this.gate);
+        this.rerankStage = new RerankStage_1.RerankStage(embedder, logger);
+    }
+    async prepareQuery(raw) {
+        return { query: raw, translated: false };
+    }
+    async searchChunks(query, limit, project, threshold, rerankOverride, perFile = result_shaping_1.DEFAULT_PER_FILE) {
+        const { stages } = await this.searchChunksWithStages(query, limit, project, threshold, rerankOverride, perFile);
+        return stages.reranked ?? stages.vector;
+    }
+    async searchChunksWithStages(query, limit, project, threshold, rerankOverride, perFile = result_shaping_1.DEFAULT_PER_FILE) {
+        const t0 = Date.now();
+        await this.identityGuard.assertIndexMatches();
+        const plan = (0, search_plan_1.planSearch)({ limit, perFile, threshold, rerankOverride, rerankAvailable: !!this.embedder.rerank }, this.config);
+        this.logger.debug('ChunkSearch: searchChunks', {
+            query: query.slice(0, 120), limit, fetchLimit: plan.fetchLimit, project, threshold: plan.threshold.value,
+        });
+        const tEmbed0 = Date.now();
+        const embedding = await this.embedder.embed(query, 'query');
+        const embedMs = Date.now() - tEmbed0;
+        const pool = await this.fetcher.fetch(embedding, plan, project);
+        this.logger.debug('ChunkSearch: searchChunks candidates', {
+            count: pool.candidates.length,
+            scores: pool.candidates.map(r => r.score),
+            files: pool.candidates.map(r => r.filePath),
+            ms: Date.now() - t0,
+        });
+        const vector = (0, result_shaping_1.limitPerFile)(pool.candidates, limit, perFile);
+        const rerank = plan.reranking ? await this.rerankStage.run(query, pool.candidates, vector, plan, t0) : undefined;
+        this.logger.info('search metrics', (0, search_metrics_1.searchMetrics)(query, {
+            fetchLimit: plan.fetchLimit, candidates: pool.candidates, results: rerank?.reranked ?? vector, poolSaturated: pool.poolSaturated, indexParams: pool.indexParams, threshold: plan.threshold,
+            embedMs, dbMs: pool.dbMs, rerankMs: rerank?.rerankMs ?? 0, totalMs: Date.now() - t0,
+        }));
+        return {
+            pool: pool.candidates,
+            stages: rerank ? { vector, reranked: rerank.reranked } : { vector },
+            rerankFailed: rerank?.rerankFailed ?? false,
+            fetchLimit: plan.fetchLimit,
+            indexParams: pool.indexParams,
+            threshold: plan.threshold,
+        };
+    }
+    async fetchNeighbors(results) {
+        const t0 = Date.now();
+        if (results.length === 0)
+            return [];
+        this.logger.debug('ChunkSearch: fetchNeighbors', { count: results.length });
+        const values = results.map((_, i) => `(${i}, $${i * 2 + 1}, $${i * 2 + 2}::int)`).join(',');
+        const params = results.flatMap(r => [r.filePath, r.startLine]);
+        const rows = await this.db.query(`SELECT r.idx,
+              prev."serviceName" AS prev_sn, prev."filePath" AS prev_fp, prev."startLine" AS prev_sl, prev.content AS prev_c, prev."ownerPath" AS prev_op,
+              next."serviceName" AS next_sn, next."filePath" AS next_fp, next."startLine" AS next_sl, next.content AS next_c, next."ownerPath" AS next_op
+       FROM (VALUES ${values}) r(idx, fp, sl)
+       LEFT JOIN LATERAL (
+         SELECT "serviceName", "filePath", "startLine", content, "ownerPath"
+         FROM code_chunk WHERE "filePath" = r.fp AND "startLine" < r.sl
+         ORDER BY "startLine" DESC LIMIT 1
+       ) prev ON true
+       LEFT JOIN LATERAL (
+         SELECT "serviceName", "filePath", "startLine", content, "ownerPath"
+         FROM code_chunk WHERE "filePath" = r.fp AND "startLine" > r.sl
+         ORDER BY "startLine" ASC LIMIT 1
+       ) next ON true
+       ORDER BY r.idx`, params);
+        const neighbors = rows.map((row, i) => ({
+            result: results[i],
+            prevChunk: row.prev_fp ? { serviceName: row.prev_sn, filePath: row.prev_fp, startLine: row.prev_sl, content: row.prev_c, ownerPath: row.prev_op ?? null } : null,
+            nextChunk: row.next_fp ? { serviceName: row.next_sn, filePath: row.next_fp, startLine: row.next_sl, content: row.next_c, ownerPath: row.next_op ?? null } : null,
+        }));
+        this.logger.debug('ChunkSearch: fetchNeighbors result', {
+            withPrev: neighbors.filter(n => n.prevChunk).length,
+            withNext: neighbors.filter(n => n.nextChunk).length,
+            ms: Date.now() - t0,
+        });
+        return neighbors;
+    }
+    async explainNoResults(project) {
+        try {
+            const rows = await this.db.query(project
+                ? `SELECT EXISTS (SELECT 1 FROM code_chunk WHERE "serviceName" = $1) AS present`
+                : `SELECT EXISTS (SELECT 1 FROM code_chunk) AS present`, project ? [project] : []);
+            return rows[0]?.present ? 'no-candidates' : 'empty-scope';
+        }
+        catch (err) {
+            this.logger.warn('ChunkSearch: explainNoResults lookup failed', { err, project });
+            return 'lookup-failed';
+        }
+    }
+}
+exports.ChunkSearch = ChunkSearch;

package/dist/src/search/DependencyGraph.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from '../config';
+import type { IDatabase, ILogger } from '../interfaces';
+import type { DependencyRow, GraphContext, IDependencyGraph } from '../interfaces/IDependencyGraph';
+import type { SearchResult } from '../interfaces/IChunkSearch';
+import type { ProjectRoots } from '../workspace/ProjectRoots';
+export declare class DependencyGraph implements IDependencyGraph {
+    private db;
+    private roots;
+    private config;
+    private logger;
+    constructor(db: IDatabase, roots: ProjectRoots, config: Config, logger: ILogger);
+    getProjectEdges(): Promise<{
+        from: string;
+        to: string;
+    }[]>;
+    fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
+    getDependencies(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getDependents(filePath: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+}

package/dist/src/search/DependencyGraph.js

@@ -0,0 +1,180 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyGraph = void 0;
+const path = __importStar(require("path"));
+const dependency_traversal_1 = require("../dependency-traversal");
+const index_paths_1 = require("./index-paths");
+class DependencyGraph {
+    db;
+    roots;
+    config;
+    logger;
+    constructor(db, roots, config, logger) {
+        this.db = db;
+        this.roots = roots;
+        this.config = config;
+        this.logger = logger;
+    }
+    async getProjectEdges() {
+        const rows = await this.db.query(`SELECT DISTINCT project, "toFile" FROM code_dependency`);
+        const byRelPath = [...this.roots.entries()]
+            .map(([name, abs]) => ({ name, rel: path.relative(this.config.workspaceRoot, abs) }))
+            .sort((a, b) => b.rel.length - a.rel.length);
+        const ownerOf = (toFile) => {
+            for (const { name, rel } of byRelPath) {
+                if (toFile === rel || toFile.startsWith(rel + path.sep) || toFile.startsWith(rel + '/'))
+                    return name;
+            }
+            return null;
+        };
+        const seen = new Set();
+        const edges = [];
+        for (const { project, toFile } of rows) {
+            const to = ownerOf(toFile);
+            if (!to || to === project)
+                continue;
+            const key = project + ' ' + to;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            edges.push({ from: project, to });
+        }
+        return edges;
+    }
+    async fetchGraphContext(results) {
+        const t0 = Date.now();
+        const files = [...new Set(results.map(r => r.filePath))];
+        this.logger.debug('DependencyGraph: fetchGraphContext', { files: files.length });
+        if (files.length === 0)
+            return new Map();
+        const proportionalLimit = Math.max(2000, files.length * 100);
+        const values = files.map((_, i) => `($${i + 1}::text)`).join(', ');
+        const rows = await this.db.query(`SELECT r.fp AS "filePath", 'import' AS direction, d."toFile" AS related
+         FROM (VALUES ${values}) AS r(fp)
+         JOIN code_dependency d ON d."fromFile" = r.fp
+         WHERE NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('d."toFile"')}
+
+         UNION ALL
+
+         SELECT r.fp AS "filePath", 'usedby' AS direction, d."fromFile" AS related
+         FROM (VALUES ${values}) AS r(fp)
+         JOIN code_dependency d ON d."toFile" = r.fp
+         WHERE NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('d."fromFile"')}
+
+         LIMIT ${proportionalLimit}`, files);
+        const ctx = new Map();
+        for (const filePath of files)
+            ctx.set(filePath, { imports: new Set(), usedBy: new Set() });
+        for (const row of rows) {
+            const g = ctx.get(row.filePath);
+            if (row.direction === 'import')
+                g.imports.add(row.related);
+            else
+                g.usedBy.add(row.related);
+        }
+        this.logger.debug('DependencyGraph: fetchGraphContext result', { files: files.length, rows: rows.length, ms: Date.now() - t0 });
+        const result = new Map();
+        for (const [fp, g] of ctx)
+            result.set(fp, {
+                imports: [...g.imports].slice(0, 50),
+                usedBy: [...g.usedBy].slice(0, 50),
+            });
+        return result;
+    }
+    async getDependencies(filePath, symbol = null, transitive = false) {
+        const t0 = Date.now();
+        this.logger.debug('DependencyGraph: getDependencies', { filePath, symbol, transitive });
+        const params = [filePath];
+        let symbolFilter = '';
+        if (symbol) {
+            params.push(symbol);
+            symbolFilter = `AND "toSymbol" = $${params.length}`;
+        }
+        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType", min("id"::text) AS "id"
+       FROM code_dependency
+       WHERE "fromFile" = $1 AND NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('"toFile"')}
+       ${symbolFilter}
+       GROUP BY "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+       ORDER BY "toFile", min("id"::text)`, params);
+        if (!transitive) {
+            this.logger.debug('DependencyGraph: getDependencies result', { direct: direct.length, ms: Date.now() - t0 });
+            return direct;
+        }
+        const neighbours = async (frontier) => {
+            const rows = await this.db.query(`SELECT DISTINCT "fromFile", "toFile" FROM code_dependency
+         WHERE "fromFile" = ANY($1::text[]) AND NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('"toFile"')}`, [frontier]);
+            return rows.map(r => ({ from: r.fromFile, to: r.toFile }));
+        };
+        const indirect = (await (0, dependency_traversal_1.traverse)(filePath, neighbours)).map(r => ({
+            toFile: r.file, depth: r.depth, via: r.via,
+            fromFile: null, fromSymbol: null, toSymbol: null, depType: null,
+        }));
+        this.logger.debug('DependencyGraph: getDependencies result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
+        return [...direct, ...indirect];
+    }
+    async getDependents(filePath, symbol = null, transitive = false) {
+        const t0 = Date.now();
+        this.logger.debug('DependencyGraph: getDependents', { filePath, symbol, transitive });
+        const params = [filePath];
+        let symbolFilter = '';
+        if (symbol) {
+            params.push(symbol);
+            symbolFilter = `AND "toSymbol" = $${params.length}`;
+        }
+        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType", min("id"::text) AS "id"
+       FROM code_dependency
+       WHERE "toFile" = $1 AND NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('"fromFile"')}
+       ${symbolFilter}
+       GROUP BY "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+       ORDER BY "fromFile", min("id"::text)`, params);
+        if (!transitive) {
+            this.logger.debug('DependencyGraph: getDependents result', { direct: direct.length, ms: Date.now() - t0 });
+            return direct;
+        }
+        const neighbours = async (frontier) => {
+            const rows = await this.db.query(`SELECT DISTINCT "fromFile", "toFile" FROM code_dependency
+         WHERE "toFile" = ANY($1::text[]) AND NOT ${(0, index_paths_1.OUTSIDE_WORKSPACE_VALUE)('"fromFile"')}`, [frontier]);
+            return rows.map(r => ({ from: r.toFile, to: r.fromFile }));
+        };
+        const indirect = (await (0, dependency_traversal_1.traverse)(filePath, neighbours)).map(r => ({
+            fromFile: r.file, depth: r.depth, via: r.via,
+            toFile: null, fromSymbol: null, toSymbol: null, depType: null,
+        }));
+        this.logger.debug('DependencyGraph: getDependents result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
+        return [...direct, ...indirect];
+    }
+}
+exports.DependencyGraph = DependencyGraph;

package/dist/src/search/IndexIdentityGuard.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from '../config';
+import type { IDatabase, IEmbedder } from '../interfaces';
+import type { IIndexIdentityGuard } from '../interfaces/IIndexIdentityGuard';
+export declare class IndexIdentityGuard implements IIndexIdentityGuard {
+    private db;
+    private embedder;
+    private config;
+    constructor(db: IDatabase, embedder: IEmbedder, config: Config);
+    assertIndexMatches(): Promise<void>;
+    private compareIndexed;
+}

package/dist/src/search/IndexIdentityGuard.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexIdentityGuard = void 0;
+const legacy_ollama_index_1 = require("../services/legacy-ollama-index");
+class IndexIdentityGuard {
+    db;
+    embedder;
+    config;
+    constructor(db, embedder, config) {
+        this.db = db;
+        this.embedder = embedder;
+        this.config = config;
+    }
+    async assertIndexMatches() {
+        const meta = await this.db.readIndexMeta();
+        if (meta) {
+            this.compareIndexed(meta.provider, meta.model, meta.dimensions);
+            return;
+        }
+        if (await (0, legacy_ollama_index_1.hasIndexedChunks)(this.db)) {
+            this.compareIndexed(legacy_ollama_index_1.LEGACY_OLLAMA_IDENTITY.provider, legacy_ollama_index_1.LEGACY_OLLAMA_IDENTITY.model, null);
+        }
+    }
+    compareIndexed(indexedProvider, indexedModel, indexedDimensions) {
+        const { provider, model } = this.config.embedding;
+        if (indexedProvider !== provider || indexedModel !== model) {
+            throw new Error(`Index was built with ${indexedProvider}/${indexedModel} but the config selects ${provider}/${model}. ` +
+                `Run \`rag-index --reindex\` to rebuild the index for the new model.`);
+        }
+        const dim = this.embedder.dimensions;
+        if (indexedDimensions != null && dim > 0 && dim !== indexedDimensions) {
+            throw new Error(`Index was built at ${indexedDimensions} dimensions but ${provider}/${model} now resolves to ${dim}. ` +
+                `Run \`rag-index --reindex\` to rebuild the index at the new dimension.`);
+        }
+    }
+}
+exports.IndexIdentityGuard = IndexIdentityGuard;

package/dist/src/search/ProjectCatalog.d.ts

@@ -0,0 +1,11 @@
+import type { IDatabase } from '../interfaces';
+import type { IProjectCatalog, ProjectRow } from '../interfaces/IProjectCatalog';
+import { type WorkspaceFs } from '../workspace/fs-access';
+import type { ProjectRoots } from '../workspace/ProjectRoots';
+export declare class ProjectCatalog implements IProjectCatalog {
+    private db;
+    private roots;
+    private fs;
+    constructor(db: IDatabase, roots: ProjectRoots, fs: WorkspaceFs);
+    listProjects(): Promise<ProjectRow[]>;
+}

package/dist/src/search/ProjectCatalog.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectCatalog = void 0;
+const file_utils_1 = require("../file-utils");
+const fs_access_1 = require("../workspace/fs-access");
+const EMPTY_META = { description: null, stack: null, notes: null, relations: null };
+class ProjectCatalog {
+    db;
+    roots;
+    fs;
+    constructor(db, roots, fs) {
+        this.db = db;
+        this.roots = roots;
+        this.fs = fs;
+    }
+    async listProjects() {
+        const rows = await this.db.query(`SELECT "serviceName", COUNT(*)::int AS chunks
+       FROM code_chunk
+       GROUP BY "serviceName"
+       ORDER BY "serviceName"`);
+        return Promise.all(rows.map(async (r) => {
+            const projectRoot = this.roots.resolveProjectRoot(r.serviceName);
+            const meta = (0, file_utils_1.readRagMeta)(projectRoot);
+            let rootError = null;
+            try {
+                await this.fs.stat(projectRoot);
+            }
+            catch (err) {
+                rootError = (0, fs_access_1.errorCode)(err);
+            }
+            return {
+                ...r, path: projectRoot, relPath: this.roots.toRel(projectRoot), rootError,
+                ...(typeof meta === 'object' ? meta : EMPTY_META),
+            };
+        }));
+    }
+}
+exports.ProjectCatalog = ProjectCatalog;

package/dist/src/search/SymbolLookup.d.ts

@@ -0,0 +1,24 @@
+import type { Config } from '../config';
+import type { IDatabase, ILogger } from '../interfaces';
+import type { FindSymbolResult, GrepSymbolResult, ISymbolLookup, SymbolKind } from '../interfaces/ISymbolLookup';
+import type { GrepRunner } from '../workspace/GrepRunner';
+import type { ProjectRoots } from '../workspace/ProjectRoots';
+import type { ToolPaths } from '../workspace/ToolPaths';
+export declare class SymbolLookup implements ISymbolLookup {
+    private db;
+    private grep;
+    private roots;
+    private paths;
+    private config;
+    private logger;
+    private readonly textSearch;
+    private readonly gate;
+    private readonly indexQuery;
+    private readonly grepFallback;
+    constructor(db: IDatabase, grep: GrepRunner, roots: ProjectRoots, paths: ToolPaths, config: Config, logger: ILogger);
+    grepSymbol(symbol: string, rootDir: string, excludeFile: string): Promise<GrepSymbolResult>;
+    findSymbol(name: string, project: string | null, kind: SymbolKind): Promise<FindSymbolResult>;
+    private findSymbolFromIndex;
+    private indexedElsewhere;
+    private similarOrNone;
+}

package/dist/src/search/SymbolLookup.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SymbolLookup = void 0;
+const symbol_name_1 = require("../symbol-name");
+const symbol_sql_1 = require("./symbol-sql");
+const find_symbol_constants_1 = require("./symbols/find-symbol-constants");
+const SymbolGrepFallback_1 = require("./symbols/SymbolGrepFallback");
+const SymbolIndexQuery_1 = require("./symbols/SymbolIndexQuery");
+const SymbolTextSearch_1 = require("./symbols/SymbolTextSearch");
+const TargetColumnGate_1 = require("./symbols/TargetColumnGate");
+const NO_SIMILAR = { names: [], truncated: false };
+class SymbolLookup {
+    db;
+    grep;
+    roots;
+    paths;
+    config;
+    logger;
+    textSearch;
+    gate;
+    indexQuery;
+    grepFallback;
+    constructor(db, grep, roots, paths, config, logger) {
+        this.db = db;
+        this.grep = grep;
+        this.roots = roots;
+        this.paths = paths;
+        this.config = config;
+        this.logger = logger;
+        this.textSearch = new SymbolTextSearch_1.SymbolTextSearch(grep, roots, config, logger);
+        this.gate = new TargetColumnGate_1.TargetColumnGate(db);
+        this.indexQuery = new SymbolIndexQuery_1.SymbolIndexQuery(db, this.gate);
+        this.grepFallback = new SymbolGrepFallback_1.SymbolGrepFallback(grep, paths, config, logger);
+    }
+    grepSymbol(symbol, rootDir, excludeFile) {
+        return this.textSearch.search(symbol, rootDir, excludeFile);
+    }
+    findSymbol(name, project, kind) {
+        const parsed = (0, symbol_name_1.parseFindSymbolName)(name);
+        if (!parsed)
+            throw new Error('Invalid symbol name');
+        return this.findSymbolFromIndex(parsed, project, kind);
+    }
+    async findSymbolFromIndex(parsed, project, kind) {
+        const t0 = Date.now();
+        this.logger.debug('SymbolLookup: findSymbol', { parsed, project, kind, source: 'index' });
+        const isGraphqlKind = find_symbol_constants_1.GRAPHQL_KINDS.has(kind);
+        const grepped = parsed.form === 'bare' || parsed.form === 'qualified';
+        let indexed;
+        try {
+            indexed = await this.indexQuery.query(parsed, project, kind);
+            this.logger.debug('SymbolLookup: findSymbol result', { source: 'index', hits: indexed.hits.length, truncated: indexed.truncated, ms: Date.now() - t0 });
+        }
+        catch (err) {
+            this.logger.warn('SymbolLookup: symbol index unavailable', { err, ms: Date.now() - t0 });
+            if (isGraphqlKind)
+                throw err;
+            if (!grepped)
+                return { hits: [], truncated: false, grep: find_symbol_constants_1.COMPLETE, similar: NO_SIMILAR };
+            return { ...(await this.grepFallback.run(parsed, project, kind)), similar: NO_SIMILAR };
+        }
+        if (indexed.hits.length > 0)
+            return { ...indexed, grep: find_symbol_constants_1.COMPLETE, similar: NO_SIMILAR };
+        if (isGraphqlKind || !grepped)
+            return { hits: [], truncated: false, grep: find_symbol_constants_1.COMPLETE, similar: NO_SIMILAR };
+        let found;
+        if (parsed.form === 'qualified' && await this.indexedElsewhere(parsed.name, project, kind)) {
+            found = { hits: [], truncated: false, grep: { outcome: 'other-container' } };
+        }
+        else {
+            found = await this.grepFallback.run(parsed, project, kind);
+        }
+        if (found.hits.length > 0)
+            return { ...found, similar: NO_SIMILAR };
+        const exactFirst = found.grep.outcome === 'other-container' || kind !== 'all';
+        return { ...found, similar: await this.similarOrNone(parsed.name, project, exactFirst) };
+    }
+    async indexedElsewhere(name, project, kind) {
+        try {
+            return await (0, symbol_sql_1.symbolIndexedElsewhere)(this.db, name, project, kind);
+        }
+        catch (err) {
+            this.logger.warn('SymbolLookup: findSymbol other-container check failed', { err, name, project });
+            return false;
+        }
+    }
+    async similarOrNone(name, project, exactFirst) {
+        try {
+            return await (0, symbol_sql_1.similarSymbolNames)(this.db, name, project, exactFirst);
+        }
+        catch (err) {
+            this.logger.warn('SymbolLookup: findSymbol similar-name lookup failed', { err, name, project });
+            return NO_SIMILAR;
+        }
+    }
+}
+exports.SymbolLookup = SymbolLookup;

package/dist/src/search/chunks/CandidateFetcher.d.ts

@@ -0,0 +1,19 @@
+import type { IDatabase } from '../../interfaces';
+import type { SearchResult } from '../../interfaces/IChunkSearch';
+import type { IterativeScanGate } from './IterativeScanGate';
+import type { SearchPlan } from './search-plan';
+export interface CandidatePool {
+    candidates: SearchResult[];
+    poolSaturated: boolean;
+    indexParams: {
+        efSearch: number;
+        iterativeScan: string;
+    };
+    dbMs: number;
+}
+export declare class CandidateFetcher {
+    private db;
+    private gate;
+    constructor(db: IDatabase, gate: IterativeScanGate);
+    fetch(embedding: number[], plan: SearchPlan, project: string | null): Promise<CandidatePool>;
+}

package/dist/src/search/chunks/CandidateFetcher.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CandidateFetcher = void 0;
+const hnsw_settings_1 = require("../../hnsw-settings");
+class CandidateFetcher {
+    db;
+    gate;
+    constructor(db, gate) {
+        this.db = db;
+        this.gate = gate;
+    }
+    async fetch(embedding, plan, project) {
+        const params = [`[${embedding}]`, plan.threshold.value, plan.dbLimit];
+        let projectFilter = '';
+        if (project) {
+            params.push(project);
+            projectFilter = `AND "serviceName" = $${params.length}`;
+        }
+        const iterative = await this.gate.enabled();
+        const settings = (0, hnsw_settings_1.hnswSettings)(plan.dbLimit, iterative);
+        const indexParams = {
+            efSearch: settings['hnsw.ef_search'],
+            iterativeScan: iterative ? hnsw_settings_1.ITERATIVE_SCAN_MODE : 'off',
+        };
+        const tDb0 = Date.now();
+        const fetched = await this.db.queryWithLocalSettings(settings, `SELECT "serviceName", "filePath", "startLine", content, "ownerPath",
+              ROUND((embedding <=> $1)::numeric, 4)::float8 AS score
+       FROM code_chunk
+       WHERE embedding <=> $1 < $2
+       ${projectFilter}
+       ORDER BY embedding <=> $1
+       LIMIT $3`, params);
+        const dbMs = Date.now() - tDb0;
+        fetched.sort((a, b) => a.score - b.score);
+        const poolSaturated = fetched.length > plan.fetchLimit;
+        const candidates = fetched.slice(0, plan.fetchLimit);
+        return { candidates, poolSaturated, indexParams, dbMs };
+    }
+}
+exports.CandidateFetcher = CandidateFetcher;

package/dist/src/search/chunks/IterativeScanGate.d.ts

@@ -0,0 +1,10 @@
+import type { IDatabase, ILogger } from '../../interfaces';
+export declare class IterativeScanGate {
+    private db;
+    private logger;
+    private pgvectorVersionRead?;
+    private degradedScanWarned;
+    constructor(db: IDatabase, logger: ILogger);
+    enabled(): Promise<boolean>;
+    private warnDegraded;
+}

package/dist/src/search/chunks/IterativeScanGate.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IterativeScanGate = void 0;
+const hnsw_settings_1 = require("../../hnsw-settings");
+class IterativeScanGate {
+    db;
+    logger;
+    pgvectorVersionRead;
+    degradedScanWarned = false;
+    constructor(db, logger) {
+        this.db = db;
+        this.logger = logger;
+    }
+    async enabled() {
+        const read = this.pgvectorVersionRead ??= this.db.pgvectorVersion().then(v => {
+            if (v === null)
+                throw new Error('vector extension not found in pg_extension');
+            return v;
+        });
+        let version;
+        try {
+            version = await read;
+        }
+        catch (err) {
+            if (this.pgvectorVersionRead === read)
+                this.pgvectorVersionRead = undefined;
+            this.warnDegraded('unknown', err);
+            return false;
+        }
+        if ((0, hnsw_settings_1.supportsIterativeScan)(version))
+            return true;
+        this.warnDegraded(version);
+        return false;
+    }
+    warnDegraded(version, err) {
+        if (this.degradedScanWarned)
+            return;
+        this.degradedScanWarned = true;
+        this.logger.warn(`IterativeScanGate: pgvector ${version} lacks hnsw.iterative_scan — filtered searches on large projects may return fewer candidates than requested; upgrade to pgvector ≥ 0.8`, err ? { err } : undefined);
+    }
+}
+exports.IterativeScanGate = IterativeScanGate;