codesearch-mcp 0.2.2-alpha → 0.3.0-alpha

package/dist/src/services/SearcherService.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearcherService = void 0;
+exports.rerankDocument = rerankDocument;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const readline = __importStar(require("readline"));
@@ -42,70 +43,327 @@ const file_utils_1 = require("../file-utils");
 const MonorepoAwareDiscoveryService_1 = require("./MonorepoAwareDiscoveryService");
 const legacy_ollama_index_1 = require("./legacy-ollama-index");
 const symbol_name_1 = require("../symbol-name");
+const dependency_traversal_1 = require("../dependency-traversal");
+const result_shaping_1 = require("../search/result-shaping");
+const hnsw_settings_1 = require("../hnsw-settings");
 const SILENT_LOGGER = {
     debug() { },
     info() { },
     warn() { },
     error() { },
-    metric() { },
+    withContext(_, fn) { return fn(); },
 };
+const NODE_FS = {
+    realpath: p => fs.promises.realpath(p),
+    stat: p => fs.promises.stat(p),
+    readdir: p => fs.promises.readdir(p, { withFileTypes: true }),
+    createReadStream: p => fs.createReadStream(p, { encoding: 'utf-8' }),
+};
+const GRAPHQL_KINDS = new Set([
+    'graphql_query', 'graphql_mutation', 'graphql_subscription', 'graphql_field', 'graphql_type',
+]);
 const EMPTY_META = { description: null, stack: null, notes: null, relations: null };
 const GREP_MAX_RESULTS = 200;
 const GREP_RAW_LIMIT = GREP_MAX_RESULTS * 5;
 const GREP_EXCLUDE_DIRS = [...file_utils_1.IGNORE_DIRS].map(d => `--exclude-dir=${d}`);
 const FIND_SYMBOL_LIMIT = 50;
 const FIND_SYMBOL_RAW_LIMIT = FIND_SYMBOL_LIMIT * 10;
+const PATH_CANDIDATE_LIMIT = 3;
+const INDEX_PATH_COLUMNS = [
+    { table: 'code_chunk', column: '"filePath"', content: true },
+    { table: 'code_symbol', column: '"filePath"', content: true },
+    { table: 'code_dependency', column: '"fromFile"', content: true },
+    { table: 'code_call', column: '"fromFile"', content: true },
+    { table: 'code_dependency', column: '"toFile"', content: false },
+    { table: 'code_call', column: '"calleeFile"', content: false },
+];
+const OUTSIDE_WORKSPACE_VALUE = (col) => `(${col} = '..' OR ${col} LIKE '../%')`;
+function stripTrailingSlash(p) {
+    return p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p;
+}
+function isWithin(p, root) {
+    if (root === '.')
+        return true;
+    if (root === '/')
+        return p.startsWith('/');
+    return p === root || p.startsWith(root + '/');
+}
+function errorCode(err) {
+    return err?.code ?? 'EIO';
+}
+function rerankDocument(row) {
+    const symbol = row.ownerPath ? ` | Symbol: ${oneLine(row.ownerPath)}` : '';
+    return `File: ${oneLine(row.filePath)}${symbol}\n${row.content}`;
+}
+function oneLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
 class SearcherService {
     db;
     embedder;
     discovery;
     config;
     logger;
-    constructor(db, embedder, discovery, config, logger = SILENT_LOGGER) {
+    fs;
+    constructor(db, embedder, discovery, config, logger = SILENT_LOGGER, fsDeps = {}) {
         this.db = db;
         this.embedder = embedder;
         this.discovery = discovery;
         this.config = config;
         this.logger = logger;
+        this.fs = { ...NODE_FS, ...fsDeps };
     }
-    /** Lazily-built, cached map of project name → real filesystem root. */
+    targetColumnPresent = false;
+    realRootCache;
     rootMap;
-    /** Cached, lazily-built map of leaf project name → real filesystem root (via discovery). */
+    pgvectorVersionRead;
+    degradedScanWarned = false;
+    async iterativeScanEnabled() {
+        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.warnDegradedScan('unknown', err);
+            return false;
+        }
+        if ((0, hnsw_settings_1.supportsIterativeScan)(version))
+            return true;
+        this.warnDegradedScan(version);
+        return false;
+    }
+    warnDegradedScan(version, err) {
+        if (this.degradedScanWarned)
+            return;
+        this.degradedScanWarned = true;
+        this.logger.warn(`SearcherService: 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);
+    }
     projectRootMap() {
         if (!this.rootMap) {
             this.rootMap = new Map((0, MonorepoAwareDiscoveryService_1.toLeafProjects)(this.discovery.discover(this.config.workspaceRoot)).map(p => [p.name, p.path]));
         }
         return this.rootMap;
     }
-    /**
-     * Resolve a project name to its real filesystem root. Uses discovery (leaf
-     * projects) so nested-monorepo names like `repo/app` map to their true path;
-     * falls back to `join(workspaceRoot, name)` when the name is unknown (e.g. a
-     * project since removed from disk, or a flat project not surfaced by discovery).
-     */
     resolveProjectRoot(name) {
         let root = this.projectRootMap().get(name);
         if (root === undefined) {
-            // Cache miss — the project may have been added/renamed on disk since the
-            // map was built (mcp/web servers are long-lived). Rebuild once and retry
-            // before the flat fallback, which is wrong for nested-monorepo names
-            // (`repo/app` lives at `repo/apps/app`, not `repo/app`).
             this.rootMap = undefined;
             root = this.projectRootMap().get(name);
         }
         return root ?? path.join(this.config.workspaceRoot, name);
     }
-    /**
-     * Project-level dependency edges aggregated from `code_dependency`: an edge
-     * `A → B` means some file in project A imports a file owned by project B.
-     * Used by the graph to draw links between a monorepo's sub-projects. Only
-     * edges whose target file belongs to an indexed project are returned (targets
-     * outside any indexed project — e.g. unindexed libs — are skipped).
-     */
+    toRel(absPath) {
+        return path.relative(this.config.workspaceRoot, absPath) || '.';
+    }
+    toAbs(relPath) {
+        return relPath === '.' ? this.workspaceRoot() : path.join(this.workspaceRoot(), relPath);
+    }
+    workspaceRoot() {
+        return stripTrailingSlash(path.posix.normalize(this.config.workspaceRoot));
+    }
+    async realWorkspaceRoot() {
+        if (this.realRootCache !== undefined)
+            return this.realRootCache;
+        try {
+            this.realRootCache = await this.fs.realpath(this.workspaceRoot());
+            return this.realRootCache;
+        }
+        catch (err) {
+            this.logger.warn('SearcherService: workspaceRoot real path unavailable', { reason: errorCode(err) });
+            return null;
+        }
+    }
+    async resolveToolPath(input) {
+        if (input == null || input === '')
+            return { ok: false, reason: 'invalid', missing: true };
+        if (input.includes('\\'))
+            return { ok: false, reason: 'invalid', missing: false };
+        if (path.posix.isAbsolute(input)) {
+            const abs = stripTrailingSlash(path.posix.normalize(input));
+            const realRoot = await this.realWorkspaceRoot();
+            for (const root of realRoot ? [this.workspaceRoot(), realRoot] : [this.workspaceRoot()]) {
+                if (!isWithin(abs, root))
+                    continue;
+                const relative = abs === root ? '.' : abs.slice(root === '/' ? 1 : root.length + 1);
+                return { ok: false, reason: 'absolute', relative };
+            }
+            return { ok: false, reason: 'outside_workspace' };
+        }
+        const relPath = stripTrailingSlash(path.posix.normalize(input));
+        if (relPath === '..' || relPath.startsWith('../'))
+            return { ok: false, reason: 'outside_workspace' };
+        return { ok: true, relPath, absPath: this.toAbs(relPath) };
+    }
+    async realLocation(absPath) {
+        const root = (await this.realWorkspaceRoot()) ?? this.workspaceRoot();
+        let existing = absPath;
+        const rest = [];
+        for (;;) {
+            try {
+                const real = path.join(await this.fs.realpath(existing), ...rest);
+                return { ok: true, inside: isWithin(real, root) };
+            }
+            catch (err) {
+                if (errorCode(err) !== 'ENOENT')
+                    return { ok: false, code: errorCode(err) };
+                const parent = path.dirname(existing);
+                if (parent === existing)
+                    return { ok: true, inside: false };
+                rest.unshift(path.basename(existing));
+                existing = parent;
+            }
+        }
+    }
+    async checkRealLocation(relPath, absPath, kind) {
+        const loc = await this.realLocation(absPath);
+        if (!loc.ok)
+            return { ok: false, reason: 'unreadable', code: loc.code };
+        if (loc.inside)
+            return { ok: true };
+        const exempt = kind === 'file' ? await this.isContentPath(relPath) : await this.hasContentUnder(relPath);
+        return exempt ? { ok: true } : { ok: false, reason: 'outside_workspace' };
+    }
+    async pathExists(columns, predicate, param) {
+        const branches = columns.map(c => `SELECT 1 FROM ${c.table} WHERE ${predicate.replace(/\$col/g, c.column)}`);
+        const [{ exists }] = await this.db.query(`SELECT EXISTS (${branches.join(' UNION ALL ')}) AS exists`, [param]);
+        return exists;
+    }
+    isIndexedPath(relPath) {
+        return this.pathExists(INDEX_PATH_COLUMNS, '$col = $1', relPath);
+    }
+    isContentPath(relPath) {
+        return this.pathExists(INDEX_PATH_COLUMNS.filter(c => c.content), '$col = $1', relPath);
+    }
+    hasContentUnder(relPath) {
+        const prefix = relPath === '.' ? '' : (0, symbol_name_1.escapeLike)(relPath) + '/';
+        return this.pathExists(INDEX_PATH_COLUMNS.filter(c => c.content), `$col LIKE $1 ESCAPE '\\'`, prefix + '%');
+    }
+    async findPathCandidates(relPath, kind) {
+        const union = INDEX_PATH_COLUMNS.map(c => `SELECT ${c.column} AS p FROM ${c.table}`).join(' UNION ALL ');
+        const notOutside = `NOT ${OUTSIDE_WORKSPACE_VALUE('p')}`;
+        if (kind === 'file') {
+            const substituted = await this.substituteProjectName(relPath);
+            const rows = await this.db.query(`SELECT p FROM (${union}) s
+         WHERE p LIKE $1 ESCAPE '\\' AND ${notOutside}
+         GROUP BY p ORDER BY p COLLATE "C" LIMIT ${PATH_CANDIDATE_LIMIT + 1}`, ['%/' + (0, symbol_name_1.escapeLike)(relPath)]);
+            const first = substituted ? [substituted] : [];
+            return [...first, ...rows.map(r => r.p).filter(p => p !== substituted)].slice(0, PATH_CANDIDATE_LIMIT);
+        }
+        const projectRoot = this.findProjectRootByName(relPath);
+        const first = projectRoot && projectRoot !== relPath ? [projectRoot] : [];
+        const rows = await this.db.query(`SELECT d AS p FROM (
+         SELECT substring(p FROM 1 FOR position($2::text IN p) + length($3::text)) AS d
+         FROM (${union}) s
+         WHERE p LIKE $1 ESCAPE '\\' AND ${notOutside}
+       ) dirs
+       GROUP BY d ORDER BY d COLLATE "C" LIMIT ${PATH_CANDIDATE_LIMIT + 1}`, ['%/' + (0, symbol_name_1.escapeLike)(relPath) + '/%', '/' + relPath + '/', relPath]);
+        const rest = rows.map(r => r.p).filter(p => !first.includes(p));
+        return [...first, ...rest].slice(0, PATH_CANDIDATE_LIMIT);
+    }
+    async candidatesOrNone(relPath, kind) {
+        try {
+            return await this.findPathCandidates(relPath, kind);
+        }
+        catch (err) {
+            this.logger.error('SearcherService: path candidate lookup failed', { relPath, err });
+            return [];
+        }
+    }
+    async substituteProjectName(relPath) {
+        let named = [];
+        for (let attempt = 0; attempt < 2 && named.length === 0; attempt++) {
+            if (attempt === 1)
+                this.rootMap = undefined;
+            named = [...this.projectRootMap().entries()].filter(([name]) => relPath.startsWith(name + '/'));
+        }
+        const longest = named.sort((a, b) => b[0].length - a[0].length)[0];
+        if (!longest)
+            return null;
+        const [name, absRoot] = longest;
+        const root = this.toRel(absRoot);
+        if (root === name)
+            return null;
+        const candidate = (root === '.' ? '' : root + '/') + relPath.slice(name.length + 1);
+        if (await this.isIndexedPath(candidate))
+            return candidate;
+        try {
+            return (await this.fs.stat(this.toAbs(candidate))).isFile() ? candidate : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    findProjectRootByName(name) {
+        let root = this.projectRootMap().get(name);
+        if (root === undefined) {
+            this.rootMap = undefined;
+            root = this.projectRootMap().get(name);
+        }
+        return root === undefined ? null : this.toRel(root);
+    }
+    findProjectRoot(match) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (attempt === 1)
+                this.rootMap = undefined;
+            const best = [...this.projectRootMap().entries()]
+                .map(([name, abs]) => ({ name, rel: this.toRel(abs) }))
+                .filter(r => match(r.rel))
+                .sort((a, b) => b.rel.length - a.rel.length)[0];
+            if (best)
+                return best;
+        }
+        return null;
+    }
+    fallbackRoot(relPath) {
+        return this.findProjectRoot(r => isWithin(relPath, r))?.rel ?? null;
+    }
+    async checkGraphPath(relPath) {
+        if (await this.isIndexedPath(relPath))
+            return null;
+        const absPath = this.toAbs(relPath);
+        const loc = await this.realLocation(absPath);
+        if (!loc.ok)
+            return { ok: false, reason: 'unreadable', code: loc.code };
+        if (!loc.inside)
+            return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'file') };
+        let stat;
+        try {
+            stat = await this.fs.stat(absPath);
+        }
+        catch (err) {
+            if (errorCode(err) !== 'ENOENT')
+                return { ok: false, reason: 'unreadable', code: errorCode(err) };
+            return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'file') };
+        }
+        if (!stat.isFile())
+            return { ok: false, reason: 'not_a_file' };
+        return { ok: false, reason: 'not_indexed', explanation: await this.explainNotIndexed(relPath) };
+    }
+    async explainNotIndexed(relPath) {
+        const owner = this.findProjectRoot(r => r !== relPath && isWithin(relPath, r));
+        if (!owner)
+            return { kind: 'no_project' };
+        const inProject = owner.rel === '.' ? relPath : relPath.slice(owner.rel.length + 1);
+        const exclusion = (0, file_utils_1.indexingExclusion)(inProject, (0, file_utils_1.loadIgnore)(this.toAbs(owner.rel)));
+        if (exclusion)
+            return exclusion;
+        const [{ exists }] = await this.db.query(`SELECT EXISTS (
+         SELECT 1 FROM code_chunk WHERE "serviceName" = $1
+         UNION ALL SELECT 1 FROM code_symbol WHERE project = $1
+         UNION ALL SELECT 1 FROM code_dependency WHERE project = $1
+         UNION ALL SELECT 1 FROM code_call WHERE project = $1
+       ) AS exists`, [owner.name]);
+        return exists ? { kind: 'unknown' } : { kind: 'project_not_indexed', project: owner.name };
+    }
     async getProjectEdges() {
         const rows = await this.db.query(`SELECT DISTINCT project, "toFile" FROM code_dependency`);
-        // Reverse map: workspace-relative project root → name, longest first so the
-        // most specific owner wins (e.g. repo/apps/account before repo).
         const byRelPath = [...this.projectRootMap().entries()]
             .map(([name, abs]) => ({ name, rel: path.relative(this.config.workspaceRoot, abs) }))
             .sort((a, b) => b.rel.length - a.rel.length);
@@ -130,29 +388,15 @@ class SearcherService {
         }
         return edges;
     }
-    // Query translation was removed (legacy). The query is embedded as-is; the
-    // method is kept so the tool layer needs no change and `translated` is always
-    // false.
     async prepareQuery(raw) {
         return { query: raw, translated: false };
     }
-    /**
-     * Refuse when the configured embedding model disagrees with the one that built
-     * the index — embedding a query into a foreign vector space returns noise. A
-     * missing `index_meta` row with an empty (or altogether absent) `code_chunk`
-     * does not block — but a *populated* `code_chunk` with no `index_meta` row is a
-     * pre-`index_meta` install, treated as the legacy `ollama`/`bge-m3` index (same
-     * interpretation as the `rag-index` legacy-Ollama guard), read-only — this check
-     * never writes `index_meta`.
-     */
     async assertIndexMatches() {
         const meta = await this.db.readIndexMeta();
         if (meta) {
             this.compareIndexed(meta.provider, meta.model, meta.dimensions);
             return;
         }
-        // No row — a missing code_chunk table counts as empty; any other DB error
-        // while counting propagates rather than being read as "not indexed".
         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);
         }
@@ -163,14 +407,6 @@ class SearcherService {
             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.`);
         }
-        // Same model but a changed dimension (e.g. a Matryoshka `embedding.dimensions`
-        // override) would embed the query at a width the column can't hold — pgvector
-        // would throw an opaque "different vector dimensions" error mid-query. Catch
-        // it here with the friendly hint. `embedder.dimensions` is 0 when the width is
-        // only knowable by probing, in which case we skip (can't compare cheaply).
-        // `indexedDimensions` is null for the legacy-inferred identity, whose provider
-        // can never match a configured provider (ollama is no longer selectable), so
-        // this branch is unreached in that case.
         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}. ` +
@@ -182,28 +418,36 @@ class SearcherService {
        FROM code_chunk
        GROUP BY "serviceName"
        ORDER BY "serviceName"`);
-        return rows.map(r => {
+        return Promise.all(rows.map(async (r) => {
             const projectRoot = this.resolveProjectRoot(r.serviceName);
             const meta = (0, file_utils_1.readRagMeta)(projectRoot);
-            return { ...r, path: projectRoot, ...(typeof meta === 'object' ? meta : EMPTY_META) };
-        });
+            let rootError = null;
+            try {
+                await this.fs.stat(projectRoot);
+            }
+            catch (err) {
+                rootError = errorCode(err);
+            }
+            return {
+                ...r, path: projectRoot, relPath: this.toRel(projectRoot), rootError,
+                ...(typeof meta === 'object' ? meta : EMPTY_META),
+            };
+        }));
     }
-    async searchChunks(query, limit, project, threshold) {
+    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.assertIndexMatches();
         const effectiveThreshold = threshold ?? this.config.search.similarityThreshold;
-        const reranking = !!this.embedder.rerank;
-        // Candidate floor: decouple the pool size from `limit` so a small `limit`
-        // (e.g. the default 5) still gives the reranker a large-enough menu. Without
-        // a reranker the extra candidates are never reordered, so keep `limit`.
+        const reranking = rerankOverride === false ? false : !!this.embedder.rerank;
+        const perFileActive = perFile < limit;
         const fetchLimit = reranking
             ? Math.min(Math.max(limit * this.config.reranker.overfetch, this.config.reranker.candidateFloor), 200)
-            : limit;
-        // With metrics on, fetch one extra row to detect a saturated pool (more
-        // under-threshold candidates existed than the window took). The extra row is
-        // dropped before reranking so it never affects results.
-        const metricsOn = this.config.logging.searchMetrics;
-        const dbLimit = metricsOn ? fetchLimit + 1 : fetchLimit;
+            : perFileActive ? Math.min(limit * 3, 200) : limit;
+        const dbLimit = fetchLimit + 1;
         this.logger.debug('SearcherService: searchChunks', {
             query: query.slice(0, 120), limit, fetchLimit, project, threshold: effectiveThreshold,
         });
@@ -216,8 +460,14 @@ class SearcherService {
             params.push(project);
             projectFilter = `AND "serviceName" = $${params.length}`;
         }
+        const iterative = await this.iterativeScanEnabled();
+        const settings = (0, hnsw_settings_1.hnswSettings)(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.query(`SELECT "serviceName", "filePath", "startLine", content, "ownerPath",
+        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
@@ -225,9 +475,8 @@ class SearcherService {
        ORDER BY embedding <=> $1
        LIMIT $3`, params);
         const dbMs = Date.now() - tDb0;
-        // Saturated iff the extra probe row came back — more candidates were under
-        // the threshold than `fetchLimit`. Trim the probe row before reranking.
-        const poolSaturated = metricsOn && fetched.length > fetchLimit;
+        fetched.sort((a, b) => a.score - b.score);
+        const poolSaturated = fetched.length > fetchLimit;
         const candidates = fetched.slice(0, fetchLimit);
         this.logger.debug('SearcherService: searchChunks candidates', {
             count: candidates.length,
@@ -235,45 +484,45 @@ class SearcherService {
             files: candidates.map(r => r.filePath),
             ms: Date.now() - t0,
         });
-        let results;
+        const vector = (0, result_shaping_1.limitPerFile)(candidates, limit, perFile);
+        let reranked;
+        let rerankFailed = false;
         let rerankMs = 0;
-        if (!reranking || candidates.length === 0) {
-            results = candidates.slice(0, limit);
+        if (reranking && candidates.length === 0) {
+            reranked = [];
         }
-        else {
+        else if (reranking) {
             const tRerank0 = Date.now();
             try {
-                const indices = await this.embedder.rerank(query, candidates.map(r => r.content), limit);
+                const topN = perFileActive ? candidates.length : limit;
+                const indices = await this.embedder.rerank(query, candidates.map(rerankDocument), topN);
                 rerankMs = Date.now() - tRerank0;
                 this.logger.debug('SearcherService: searchChunks rerank done', { indices, ms: Date.now() - t0 });
-                // Cap at `limit`: some rerank servers ignore `top_n` and echo back every
-                // candidate, so slicing here keeps the result count within the request.
-                results = indices.filter(i => i >= 0 && i < candidates.length).slice(0, limit).map(i => candidates[i]);
+                const order = indices.filter(i => i >= 0 && i < candidates.length).map(i => candidates[i]);
+                reranked = (0, result_shaping_1.limitPerFile)(order, limit, perFile);
             }
             catch (err) {
                 rerankMs = Date.now() - tRerank0;
                 this.logger.warn('SearcherService: rerank failed, falling back to vector order', {
-                    reason: err instanceof Error ? err.message : String(err),
+                    err,
                     ms: Date.now() - t0,
                 });
-                results = candidates.slice(0, limit);
+                reranked = vector;
+                rerankFailed = true;
             }
         }
-        if (metricsOn) {
-            this.emitSearchMetrics(query, {
-                fetchLimit, candidates, results, poolSaturated, embedMs, dbMs, rerankMs, totalMs: Date.now() - t0,
-            });
-        }
-        return results;
+        this.emitSearchMetrics(query, {
+            fetchLimit, candidates, results: reranked ?? vector, poolSaturated, indexParams,
+            embedMs, dbMs, rerankMs, totalMs: Date.now() - t0,
+        });
+        return {
+            pool: candidates,
+            stages: reranked ? { vector, reranked } : { vector },
+            rerankFailed,
+            fetchLimit,
+            indexParams,
+        };
     }
-    /**
-     * Emit one structured search-tuning line (via `logger.metric`, at `info`
-     * regardless of `logging.level`). `candidates` are in cosine order, so a
-     * candidate's array index is its cosine rank — `maxCosineRankSurvived` is the
-     * deepest cosine position that survived reranking into the returned set. Read
-     * it alongside `poolSaturated` to tune `candidateFloor`/`overfetch`/threshold
-     * per hardware. Never logs chunk content, embeddings, or credentials.
-     */
     emitSearchMetrics(query, m) {
         const { candidates, results } = m;
         const contentIndex = new Map(candidates.map((c, i) => [c, i]));
@@ -282,7 +531,7 @@ class SearcherService {
         for (const r of results)
             fileCounts.set(r.filePath, (fileCounts.get(r.filePath) ?? 0) + 1);
         const topFileCount = results.length ? Math.max(...fileCounts.values()) : 0;
-        this.logger.metric('search metrics', {
+        this.logger.info('search metrics', {
             query: query.slice(0, 120),
             fetchLimit: m.fetchLimit,
             candidatesReturned: candidates.length,
@@ -293,6 +542,8 @@ class SearcherService {
             topFileShare: results.length ? +(topFileCount / results.length).toFixed(3) : 0,
             bestResultScore: results.length ? Math.min(...results.map(r => r.score)) : null,
             worstResultScore: results.length ? Math.max(...results.map(r => r.score)) : null,
+            efSearch: m.indexParams.efSearch,
+            iterativeScan: m.indexParams.iterativeScan,
             embedMs: m.embedMs,
             rerankMs: m.rerankMs,
             dbMs: m.dbMs,
@@ -335,38 +586,27 @@ class SearcherService {
     }
     async fetchGraphContext(results) {
         const t0 = Date.now();
-        const seen = new Map();
-        for (const r of results) {
-            const key = `${r.serviceName}::${r.filePath}`;
-            if (!seen.has(key))
-                seen.set(key, { filePath: r.filePath, project: r.serviceName });
-        }
-        const pairs = [...seen.values()];
-        this.logger.debug('SearcherService: fetchGraphContext', { files: pairs.length });
-        if (pairs.length === 0)
+        const files = [...new Set(results.map(r => r.filePath))];
+        this.logger.debug('SearcherService: fetchGraphContext', { files: files.length });
+        if (files.length === 0)
             return new Map();
-        const n = pairs.length;
-        // Use proportional limit: 50 imports + 50 usedBy per file
-        const proportionalLimit = Math.max(2000, n * 100);
-        const firstHalf = pairs.map((_, i) => `($${i * 2 + 1}::text, $${i * 2 + 2}::text)`).join(', ');
-        const secondHalf = pairs.map((_, i) => `($${n * 2 + i * 2 + 1}::text, $${n * 2 + i * 2 + 2}::text)`).join(', ');
-        const params = [
-            ...pairs.flatMap(p => [p.filePath, p.project]),
-            ...pairs.flatMap(p => [p.filePath, p.project]),
-        ];
+        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 ${firstHalf}) AS r(fp, proj)
-         JOIN code_dependency d ON d."fromFile" = r.fp AND d.project = r.proj
+         FROM (VALUES ${values}) AS r(fp)
+         JOIN code_dependency d ON d."fromFile" = r.fp
+         WHERE NOT ${OUTSIDE_WORKSPACE_VALUE('d."toFile"')}
 
          UNION ALL
 
          SELECT r.fp AS "filePath", 'usedby' AS direction, d."fromFile" AS related
-         FROM (VALUES ${secondHalf}) AS r(fp, proj)
-         JOIN code_dependency d ON d."toFile" = r.fp AND d.project = r.proj
+         FROM (VALUES ${values}) AS r(fp)
+         JOIN code_dependency d ON d."toFile" = r.fp
+         WHERE NOT ${OUTSIDE_WORKSPACE_VALUE('d."fromFile"')}
 
-         LIMIT ${proportionalLimit}`, params);
+         LIMIT ${proportionalLimit}`, files);
         const ctx = new Map();
-        for (const { filePath } of pairs)
+        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);
@@ -375,7 +615,7 @@ class SearcherService {
             else
                 g.usedBy.add(row.related);
         }
-        this.logger.debug('SearcherService: fetchGraphContext result', { files: pairs.length, rows: rows.length, ms: Date.now() - t0 });
+        this.logger.debug('SearcherService: 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, {
@@ -384,89 +624,65 @@ class SearcherService {
             });
         return result;
     }
-    async getDependencies(filePath, project, symbol = null, transitive = false) {
+    async getDependencies(filePath, symbol = null, transitive = false) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: getDependencies', { filePath, project, symbol, transitive });
-        const params = [filePath, project];
+        this.logger.debug('SearcherService: 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"
+        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType", min("id"::text) AS "id"
        FROM code_dependency
-       WHERE "fromFile" = $1 AND project = $2
+       WHERE "fromFile" = $1 AND NOT ${OUTSIDE_WORKSPACE_VALUE('"toFile"')}
        ${symbolFilter}
-       ORDER BY "toFile"`, params);
+       GROUP BY "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+       ORDER BY "toFile", min("id"::text)`, params);
         if (!transitive) {
             this.logger.debug('SearcherService: getDependencies result', { direct: direct.length, ms: Date.now() - t0 });
             return direct;
         }
-        const indirect = await this.db.query(`WITH RECURSIVE deps AS (
-         SELECT "toFile", 1 AS depth, "toFile" AS via
-         FROM code_dependency
-         WHERE "fromFile" = $1 AND project = $2
-
-         UNION ALL
-
-         SELECT d."toFile", deps.depth + 1, deps."toFile" AS via
-         FROM code_dependency d
-         JOIN deps ON deps."toFile" = d."fromFile"
-         WHERE d.project = $2
-           AND d."toFile" <> $1
-           AND deps.depth < 20
-       )
-       SELECT "toFile", MIN(depth) AS depth,
-              (array_agg(via ORDER BY depth))[1] AS via,
-              NULL::text AS "fromFile", NULL::text AS "fromSymbol",
-              NULL::text AS "toSymbol", NULL::text AS "depType"
-       FROM deps
-       WHERE depth > 1
-       GROUP BY "toFile"
-       ORDER BY MIN(depth), "toFile"`, [filePath, project]);
+        const neighbours = async (frontier) => {
+            const rows = await this.db.query(`SELECT DISTINCT "fromFile", "toFile" FROM code_dependency
+         WHERE "fromFile" = ANY($1::text[]) AND NOT ${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('SearcherService: getDependencies result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
         return [...direct, ...indirect];
     }
-    async getDependents(filePath, project, symbol = null, transitive = false) {
+    async getDependents(filePath, symbol = null, transitive = false) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: getDependents', { filePath, project, symbol, transitive });
-        const params = [filePath, project];
+        this.logger.debug('SearcherService: 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"
+        const direct = await this.db.query(`SELECT "fromFile", "fromSymbol", "toFile", "toSymbol", "depType", min("id"::text) AS "id"
        FROM code_dependency
-       WHERE "toFile" = $1 AND project = $2
+       WHERE "toFile" = $1 AND NOT ${OUTSIDE_WORKSPACE_VALUE('"fromFile"')}
        ${symbolFilter}
-       ORDER BY "fromFile"`, params);
+       GROUP BY "fromFile", "fromSymbol", "toFile", "toSymbol", "depType"
+       ORDER BY "fromFile", min("id"::text)`, params);
         if (!transitive) {
             this.logger.debug('SearcherService: getDependents result', { direct: direct.length, ms: Date.now() - t0 });
             return direct;
         }
-        const indirect = await this.db.query(`WITH RECURSIVE rdeps AS (
-         SELECT "fromFile", 1 AS depth, "fromFile" AS via
-         FROM code_dependency
-         WHERE "toFile" = $1 AND project = $2
-
-         UNION ALL
-
-         SELECT d."fromFile", rdeps.depth + 1, rdeps."fromFile" AS via
-         FROM code_dependency d
-         JOIN rdeps ON rdeps."fromFile" = d."toFile"
-         WHERE d.project = $2
-           AND d."fromFile" <> $1
-           AND rdeps.depth < 20
-       )
-       SELECT "fromFile", MIN(depth) AS depth,
-              (array_agg(via ORDER BY depth))[1] AS via,
-              NULL::text AS "toFile", NULL::text AS "fromSymbol",
-              NULL::text AS "toSymbol", NULL::text AS "depType"
-       FROM rdeps
-       WHERE depth > 1
-       GROUP BY "fromFile"
-       ORDER BY MIN(depth), "fromFile"`, [filePath, project]);
+        const neighbours = async (frontier) => {
+            const rows = await this.db.query(`SELECT DISTINCT "fromFile", "toFile" FROM code_dependency
+         WHERE "toFile" = ANY($1::text[]) AND NOT ${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('SearcherService: getDependents result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
         return [...direct, ...indirect];
     }
@@ -503,42 +719,21 @@ class SearcherService {
         this.logger.debug('SearcherService: getCallers result', { count: rows.length, ms: Date.now() - t0 });
         return rows;
     }
-    /**
-     * One-line warning when any project in `scope` (the given `project`, or
-     * every project with `code_chunk`/`code_symbol` rows) is outdated — shown
-     * first in `find_symbol`/`get_callers` output. Any failure to determine the
-     * scope or read markers only drops the notice (warn logged); the lookup
-     * itself is unaffected.
-     */
-    async outdatedNotice(project) {
-        try {
-            const outdated = await this.db.listOutdatedProjects(project ? [project] : null);
-            if (outdated.length === 0)
-                return null;
-            return `⚠ Indexed before member indexing: ${[...outdated].sort().join(', ')} — run rag-index --reindex; methods and qualified names may be missing.`;
-        }
-        catch (err) {
-            this.logger.warn('SearcherService: failed to determine outdated-index scope', { reason: err.message });
-            return null;
-        }
-    }
-    async grepSymbol(symbol, project, excludeFile) {
+    async grepSymbol(symbol, rootDir, excludeFile) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: grepSymbol', { symbol, project, excludeFile });
-        const projectDir = this.resolveProjectRoot(project);
+        this.logger.debug('SearcherService: grepSymbol', { symbol, rootDir, excludeFile });
         const result = await this.spawnGrep([
             '-rn', '-F', '-w',
             '-m', String(GREP_RAW_LIMIT),
             '--include=*.ts', '--include=*.tsx', '--include=*.js', '--include=*.jsx',
             ...GREP_EXCLUDE_DIRS,
             symbol,
-            projectDir,
+            this.toAbs(rootDir),
         ]);
-        if (!result.ok || result.output === null) {
-            return { matches: [], truncated: false };
-        }
+        if (!result.ok && result.output === null)
+            return { ok: false };
         const excludeAbsPath = path.join(this.config.workspaceRoot, excludeFile);
-        const all = result.output.split('\n').flatMap(line => {
+        const all = (result.output ?? '').split('\n').flatMap(line => {
             const match = line.match(/^(.+?):(\d+):/);
             if (!match)
                 return [];
@@ -548,22 +743,34 @@ class SearcherService {
             return [{ filePath: path.relative(this.config.workspaceRoot, absFile), line: parseInt(lineNum, 10) }];
         });
         const truncated = all.length > GREP_MAX_RESULTS;
-        this.logger.debug('SearcherService: grepSymbol result', { matches: Math.min(all.length, GREP_MAX_RESULTS), truncated, ms: Date.now() - t0 });
-        return { matches: all.slice(0, GREP_MAX_RESULTS), truncated };
+        this.logger.debug('SearcherService: grepSymbol result', { matches: Math.min(all.length, GREP_MAX_RESULTS), truncated, partial: !result.ok, ms: Date.now() - t0 });
+        return { ok: true, matches: all.slice(0, GREP_MAX_RESULTS), truncated, partial: !result.ok };
     }
-    // Sync wrapper: validates name (throws synchronously), then returns Promise.
-    // Every kind, including 'method', is looked up in the index first.
     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 hasTargetColumn() {
+        if (this.targetColumnPresent)
+            return true;
+        const rows = await this.db.query(`SELECT EXISTS (
+         SELECT 1 FROM information_schema.columns
+         WHERE table_schema = 'public' AND table_name = 'code_symbol' AND column_name = 'target'
+       ) AS present`);
+        const present = !!rows[0]?.present;
+        if (present)
+            this.targetColumnPresent = true;
+        return present;
+    }
     async findSymbolFromIndex(parsed, project, kind) {
         const t0 = Date.now();
         this.logger.debug('SearcherService: findSymbol', { parsed, project, kind, source: 'index' });
         const container = 'container' in parsed ? parsed.container : null;
+        const isGraphqlKind = GRAPHQL_KINDS.has(kind);
         try {
+            const hasTarget = await this.hasTargetColumn();
             const params = [parsed.name];
             let nameFilter = 'name = $1';
             let orderPrefix = '';
@@ -586,10 +793,11 @@ class SearcherService {
                 kindFilter = `AND kind = $${params.length}`;
             }
             params.push(FIND_SYMBOL_LIMIT + 1);
-            const rows = await this.db.query(`SELECT "filePath", name, kind, signature, line, col, container, "isStatic"
+            const targetSelect = hasTarget ? '"target"' : 'NULL AS target';
+            const rows = await this.db.query(`SELECT "filePath", name, kind, signature, line, col, container, "isStatic", ${targetSelect}
          FROM code_symbol
          WHERE ${nameFilter} ${projectFilter} ${kindFilter}
-         ORDER BY ${orderPrefix}project, "filePath", line
+         ORDER BY ${orderPrefix}project, "filePath", line, col, kind COLLATE "C", container COLLATE "C" NULLS FIRST
          LIMIT $${params.length}`, params);
             const truncated = rows.length > FIND_SYMBOL_LIMIT;
             const hits = rows.slice(0, FIND_SYMBOL_LIMIT).map(row => ({
@@ -601,16 +809,21 @@ class SearcherService {
                 qualified: row.container ? `${row.container}.${row.name}` : row.name,
                 isStatic: !!row.isStatic,
                 source: 'index',
+                target: row.target ?? null,
             }));
             this.logger.debug('SearcherService: findSymbol result', { source: 'index', hits: hits.length, truncated, ms: Date.now() - t0 });
             if (hits.length > 0)
                 return { hits, truncated, grepFailed: false };
+            if (isGraphqlKind)
+                return { hits: [], truncated: false, grepFailed: false };
             if (parsed.form === 'quoted' || parsed.form === 'computed')
                 return { hits: [], truncated: false, grepFailed: false };
             return this.grepFindSymbol(parsed, project, kind);
         }
         catch (err) {
-            this.logger.warn('SearcherService: symbol index unavailable, falling back to grep', { reason: err.message, ms: Date.now() - t0 });
+            this.logger.warn('SearcherService: symbol index unavailable', { err, ms: Date.now() - t0 });
+            if (isGraphqlKind)
+                throw err;
             if (parsed.form === 'quoted' || parsed.form === 'computed')
                 return { hits: [], truncated: false, grepFailed: false };
             return this.grepFindSymbol(parsed, project, kind);
@@ -618,7 +831,7 @@ class SearcherService {
     }
     async grepFindSymbol(parsed, project, kind) {
         const t0 = Date.now();
-        const grepName = parsed.name; // qualified names are grepped by their last segment, no container filter
+        const grepName = parsed.name;
         this.logger.debug('SearcherService: findSymbol', { grepName, project, kind, source: 'grep' });
         const pattern = this.buildFindSymbolPattern(grepName, kind);
         if (pattern === null)
@@ -661,124 +874,136 @@ class SearcherService {
                 qualified: grepName,
                 isStatic: false,
                 source: 'grep',
+                target: null,
             });
         }
         const truncated = parsedHits.length > FIND_SYMBOL_LIMIT;
         this.logger.debug('SearcherService: findSymbol result', { source: 'grep', hits: Math.min(parsedHits.length, FIND_SYMBOL_LIMIT), truncated, ms: Date.now() - t0 });
         return { hits: parsedHits.slice(0, FIND_SYMBOL_LIMIT), truncated, grepFailed: false };
     }
-    listFiles(relativePath, project, depth, pattern) {
+    async listFiles(relPath, depth, pattern) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: listFiles', { relativePath, project, depth, pattern });
-        const projectRoot = this.resolveProjectRoot(project);
-        const resolvedTarget = path.resolve(projectRoot, relativePath);
-        const resolvedProject = path.resolve(projectRoot);
-        if (resolvedTarget !== resolvedProject && !resolvedTarget.startsWith(resolvedProject + path.sep)) {
-            return { tree: '', error: 'Path escapes project root' };
-        }
-        if (!fs.existsSync(resolvedTarget)) {
-            return { tree: '', error: `Path not found: ${relativePath}` };
+        this.logger.debug('SearcherService: listFiles', { relPath, depth, pattern });
+        const absPath = this.toAbs(relPath);
+        const loc = await this.checkRealLocation(relPath, absPath, 'dir');
+        if (!loc.ok)
+            return loc;
+        let stat;
+        try {
+            stat = await this.fs.stat(absPath);
         }
-        if (!fs.statSync(resolvedTarget).isDirectory()) {
-            return { tree: '', error: `Not a directory: ${relativePath}` };
+        catch (err) {
+            if (errorCode(err) !== 'ENOENT')
+                return { ok: false, reason: 'unreadable', code: errorCode(err) };
+            return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'dir') };
         }
+        if (!stat.isDirectory())
+            return { ok: false, reason: 'not_a_directory' };
         const clampedDepth = Math.min(5, Math.max(1, depth));
         const lines = [];
-        this.walkDir(resolvedTarget, 0, clampedDepth - 1, pattern, lines);
+        try {
+            await this.walkDir(absPath, 0, clampedDepth - 1, pattern, lines);
+        }
+        catch (err) {
+            return { ok: false, reason: 'unreadable', code: errorCode(err) };
+        }
         this.logger.debug('SearcherService: listFiles result', { entries: lines.length, ms: Date.now() - t0 });
         if (lines.length === 0) {
-            return { tree: pattern ? `No files matching "${pattern}" found.` : '(empty directory)' };
+            return { ok: true, tree: pattern ? `No files matching "${pattern}" found.` : '(empty directory)' };
         }
-        return { tree: lines.join('\n') };
+        return { ok: true, tree: lines.join('\n') };
     }
-    async readFileAbsolute(absPath, maxLines) {
-        const t0 = Date.now();
-        this.logger.debug('SearcherService: readFileAbsolute', { absPath, maxLines });
-        const resolvedRoot = path.resolve(this.config.workspaceRoot);
-        const resolved = path.resolve(absPath);
-        if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
-            return { ok: false, reason: 'invalid_path' };
-        }
-        if (!fs.existsSync(resolved))
-            return { ok: false, reason: 'not_on_disk' };
-        const lines = [];
-        const stream = fs.createReadStream(resolved, { encoding: 'utf-8' });
+    async openableFile(relPath, absPath) {
+        const loc = await this.checkRealLocation(relPath, absPath, 'file');
+        if (!loc.ok)
+            return loc;
+        let stat;
+        try {
+            stat = await this.fs.stat(absPath);
+        }
+        catch (err) {
+            if (errorCode(err) !== 'ENOENT')
+                return { ok: false, reason: 'unreadable', code: errorCode(err) };
+            if (await this.isIndexedPath(relPath))
+                return { ok: false, reason: 'deleted' };
+            return { ok: false, reason: 'not_found', candidates: await this.candidatesOrNone(relPath, 'file') };
+        }
+        return stat.isFile() ? null : { ok: false, reason: 'not_a_file' };
+    }
+    async readLines(absPath, onLine) {
+        const stream = this.fs.createReadStream(absPath);
         const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
         let lineNo = 0;
-        let hasMore = false;
         try {
             for await (const line of rl) {
                 lineNo++;
-                if (lineNo <= maxLines) {
-                    lines.push(line);
-                }
-                else {
-                    hasMore = true;
-                    rl.close();
-                    stream.destroy();
+                if (!onLine(line, lineNo))
                     break;
-                }
             }
+            return { ok: true, lineCount: lineNo };
         }
         catch (err) {
+            return { ok: false, code: errorCode(err) };
+        }
+        finally {
             rl.close();
-            stream.destroy();
-            throw err;
+            stream.destroy?.();
         }
-        const relPath = path.relative(resolvedRoot, resolved);
-        this.logger.debug('SearcherService: readFileAbsolute result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
+    }
+    async readFile(relPath, maxLines) {
+        const t0 = Date.now();
+        this.logger.debug('SearcherService: readFile', { relPath, maxLines });
+        const absPath = this.toAbs(relPath);
+        const failure = await this.openableFile(relPath, absPath);
+        if (failure)
+            return failure;
+        const lines = [];
+        let hasMore = false;
+        const read = await this.readLines(absPath, line => {
+            if (lines.length < maxLines) {
+                lines.push(line);
+                return true;
+            }
+            hasMore = true;
+            return false;
+        });
+        if (!read.ok)
+            return { ok: false, reason: 'unreadable', code: read.code };
+        this.logger.debug('SearcherService: readFile result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
         return { ok: true, filePath: relPath, startLine: 1, endLine: lines.length, lines, hasMore };
     }
-    async readFileRange(filePath, startLine, endLine) {
+    async readFileRange(relPath, startLine, endLine) {
         const t0 = Date.now();
-        this.logger.debug('SearcherService: readFileRange', { filePath, startLine, endLine });
-        const resolvedRoot = path.resolve(this.config.workspaceRoot);
-        const absPath = path.resolve(resolvedRoot, filePath);
-        if (absPath !== resolvedRoot && !absPath.startsWith(resolvedRoot + path.sep)) {
-            return { ok: false, reason: 'invalid_path' };
-        }
-        const [{ exists }] = await this.db.query(`SELECT EXISTS (SELECT 1 FROM code_chunk WHERE "filePath" = $1) AS exists`, [filePath]);
-        if (!exists)
-            return { ok: false, reason: 'not_indexed' };
-        if (!fs.existsSync(absPath))
-            return { ok: false, reason: 'not_on_disk' };
+        this.logger.debug('SearcherService: readFileRange', { relPath, startLine, endLine });
+        if (endLine < startLine)
+            return { ok: false, reason: 'bad_range', startLine, endLine };
+        const absPath = this.toAbs(relPath);
+        const failure = await this.openableFile(relPath, absPath);
+        if (failure)
+            return failure;
         const lines = [];
-        const stream = fs.createReadStream(absPath, { encoding: 'utf-8' });
-        const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-        let lineNo = 0;
         let lastRead = 0;
         let hasMore = false;
-        try {
-            for await (const line of rl) {
-                lineNo++;
-                if (lineNo >= startLine && lineNo <= endLine)
-                    lines.push(line);
-                if (lineNo <= endLine)
-                    lastRead = lineNo;
-                if (lineNo > endLine) {
-                    hasMore = true;
-                    rl.close();
-                    stream.destroy();
-                    break;
-                }
+        const read = await this.readLines(absPath, (line, lineNo) => {
+            if (lineNo > endLine) {
+                hasMore = true;
+                return false;
             }
-        }
-        catch (err) {
-            rl.close();
-            stream.destroy();
-            throw err;
+            if (lineNo >= startLine)
+                lines.push(line);
+            lastRead = lineNo;
+            return true;
+        });
+        if (!read.ok)
+            return { ok: false, reason: 'unreadable', code: read.code };
+        if (!hasMore && startLine > Math.max(read.lineCount, 1)) {
+            return { ok: false, reason: 'past_end', lineCount: read.lineCount, startLine };
         }
         this.logger.debug('SearcherService: readFileRange result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
-        return { ok: true, filePath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
+        return { ok: true, filePath: relPath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
     }
-    walkDir(absDir, currentDepth, maxDepth, pattern, lines) {
-        let entries;
-        try {
-            entries = fs.readdirSync(absDir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
+    async walkDir(absDir, currentDepth, maxDepth, pattern, lines) {
+        const entries = await this.fs.readdir(absDir);
         entries.sort((a, b) => {
             const ad = a.isDirectory() ? 0 : 1;
             const bd = b.isDirectory() ? 0 : 1;
@@ -791,9 +1016,14 @@ class SearcherService {
                 continue;
             const indent = '  '.repeat(currentDepth);
             if (entry.isDirectory()) {
-                lines.push(`${indent}${entry.name}/`);
+                const at = lines.push(`${indent}${entry.name}/`) - 1;
                 if (currentDepth < maxDepth) {
-                    this.walkDir(path.join(absDir, entry.name), currentDepth + 1, maxDepth, pattern, lines);
+                    try {
+                        await this.walkDir(path.join(absDir, entry.name), currentDepth + 1, maxDepth, pattern, lines);
+                    }
+                    catch {
+                        lines[at] += ' (unreadable)';
+                    }
                 }
             }
             else {
@@ -803,17 +1033,14 @@ class SearcherService {
             }
         }
     }
-    /**
-     * ERE pattern for a grep-fallback kind, or null when that kind is never
-     * grepped (`function_property`/`method_signature` are index-only; a bare
-     * `constructor` search only makes sense when the name itself is `constructor`).
-     */
     buildFindSymbolPattern(name, kind) {
         if (kind === 'function_property' || kind === 'method_signature')
             return null;
+        if (GRAPHQL_KINDS.has(kind))
+            return null;
         if (kind === 'constructor')
             return name === 'constructor' ? `(^|[[:space:]])constructor[[:space:]]*\\(` : null;
-        const esc = name.replace(/\$/g, '\\$'); // ERE end-of-line metachar
+        const esc = name.replace(/\$/g, '\\$');
         const MODIFIER = '(public|private|protected|static|abstract|async|override)';
         const BOUNDARY = '(^|[^[:alnum:]_$])';
         const patterns = {
@@ -830,7 +1057,6 @@ class SearcherService {
             return Object.values(patterns).join('|');
         return patterns[kind];
     }
-    /** 1-based index of the first whole-word occurrence of `name` in `line`, or -1. */
     static wholeWordIndex(line, name) {
         const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         const re = new RegExp(`(?<![\\w$#])${escaped}(?![\\w$#])`);
@@ -860,11 +1086,6 @@ class SearcherService {
             return 'method';
         return 'variable';
     }
-    /**
-     * Async wrapper around grep to avoid blocking the event loop. `ok: false`
-     * means grep could not be spawned or exited with status ≥ 2 (distinguishable
-     * from a clean "no matches", which is `ok: true, output: null`).
-     */
     spawnGrep(args) {
         return new Promise((resolve) => {
             const proc = (0, child_process_1.spawn)('grep', args, { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -879,17 +1100,17 @@ class SearcherService {
             });
             proc.stderr.on('data', () => { });
             proc.on('error', (err) => {
-                this.logger.error('SearcherService: grep spawn failed', { reason: err.message });
-                resolve({ ok: false });
+                this.logger.error('SearcherService: grep spawn failed', { err });
+                resolve({ ok: false, output: null });
             });
             proc.on('close', (code) => {
-                // grep returns 1 for "no matches" — not an error; 2+ is a real failure
+                const output = chunks.length === 0 ? null : Buffer.concat(chunks).toString('utf-8');
                 if (code !== null && code >= 2) {
                     this.logger.warn('SearcherService: grep exited with code', { code });
-                    resolve({ ok: false });
+                    resolve({ ok: false, output });
                     return;
                 }
-                resolve({ ok: true, output: chunks.length === 0 ? null : Buffer.concat(chunks).toString('utf-8') });
+                resolve({ ok: true, output });
             });
         });
     }