codesearch-mcp 0.1.0-alpha → 0.2.0-alpha

package/dist/src/services/IndexerService.js

@@ -236,13 +236,12 @@ class IndexerService {
         const files = preCollectedFiles ?? (0, file_utils_1.collectFiles)(dir, (0, file_utils_1.loadIgnore)(dir), dir);
         this.logger.debug('IndexerService: scanAndIndex files collected', { serviceName, count: files.length, force });
         const collectedRelPaths = new Set(files.map(f => path.relative(this.config.workspaceRoot, f)));
-        const dbPaths = await this.db.query(`SELECT DISTINCT "filePath" FROM code_chunk WHERE "serviceName" = $1`, [serviceName]);
-        for (const { filePath } of dbPaths) {
-            if (!collectedRelPaths.has(filePath)) {
-                await this.db.transaction(tx => tx.delete(db_1.codeChunk).where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(db_1.codeChunk.serviceName, serviceName), (0, drizzle_orm_1.eq)(db_1.codeChunk.filePath, filePath))));
-                await this.db.query(`DELETE FROM code_dependency WHERE project = $1 AND "fromFile" = $2`, [serviceName, filePath]);
-                await this.db.query(`DELETE FROM code_dependency WHERE project = $1 AND "toFile" = $2`, [serviceName, filePath]);
-                console.log(`  Removed stale: ${path.basename(filePath)}`);
+        const knownFiles = await this.db.listKnownFiles(serviceName);
+        const staleFiles = knownFiles.filter(f => !collectedRelPaths.has(f));
+        if (staleFiles.length > 0) {
+            await this.db.deleteFiles(serviceName, staleFiles);
+            for (const f of staleFiles) {
+                console.log(`  Removed stale: ${path.basename(f)}`);
             }
         }
         const bar = new cli_progress_1.SingleBar({
@@ -346,6 +345,27 @@ class IndexerService {
         });
         return stats;
     }
+    async pruneProjects(keep) {
+        if (keep.length === 0)
+            return { removed: [], failed: [] };
+        const indexed = await this.db.listIndexedProjects();
+        const keepSet = new Set(keep);
+        const toRemove = indexed.filter(name => !keepSet.has(name));
+        const removed = [];
+        const failed = [];
+        for (const name of toRemove) {
+            try {
+                await this.db.deleteProject(name);
+                removed.push(name);
+            }
+            catch (err) {
+                console.error(`Failed to prune project ${name}: ${err.message}`);
+                this.logger.error('IndexerService: pruneProject failed', { name, reason: err.message });
+                failed.push(name);
+            }
+        }
+        return { removed, failed };
+    }
     static inferRole(relPath) {
         const p = relPath.toLowerCase();
         if (p.includes('/services/') || p.endsWith('.service.ts'))

package/dist/src/services/InfinityEmbedder.d.ts

@@ -1,79 +1,38 @@
 import type { Config } from '../config';
 import type { ILogger } from '../interfaces/ILogger';
 import { OpenAICompatibleEmbedder, type EmbedderDeps } from './OpenAICompatibleEmbedder';
-/** Result of a shell command run, mirroring the parts of `spawnSync` we use. */
-export interface CommandResult {
-    status: number | null;
-    stdout?: string;
-}
-/**
- * Extra injection seams for `InfinityEmbedder` beyond the shared `EmbedderDeps`.
- * All optional and defaulted to the real implementations; tests inject fakes so
- * `ensureModelAvailable()` runs without a live Infinity server or Docker.
- */
-export interface InfinityDeps extends EmbedderDeps {
-    /** Runs a shell command (docker), optionally with extra env. Defaults to `spawnSync`. */
-    runCommand?: (cmd: string, args: string[], env?: Record<string, string>) => CommandResult;
+import { serverRoot, probeInfinityHealth, listInfinityModels, type ProvisioningDeps } from './infinity-provisioning';
+export { serverRoot, probeInfinityHealth, listInfinityModels };
+export type { CommandResult } from './infinity-provisioning';
+/** Extra injection seams for `InfinityEmbedder` beyond the shared `EmbedderDeps`. */
+export interface InfinityDeps extends EmbedderDeps, ProvisioningDeps {
     /**
      * Path to the managed docker-compose.yml. Defaults to the file `rag-setup`
      * writes into `~/.config/codesearch-mcp/`. A missing file (or one without an
      * `infinity` service) means "external backend" — the Docker path is skipped.
      */
     composePath?: string;
-    /** Sleep between readiness polls (ms). Defaults to 2000; tests pass 0. */
-    pollIntervalMs?: number;
 }
-/**
- * Strip trailing slashes and a trailing `/embeddings` or `/v1` to get the server
- * root — Infinity serves `/health`, `/models`, `/rerank`, `/embeddings` from the
- * root, so a baseURL written with an OpenAI-style suffix must be normalized here
- * to keep the probe/models URLs aligned with the embeddings URL.
- */
-export declare function serverRoot(baseURL: string): string;
-/**
- * Probe an Infinity-style `/health` endpoint. Resolves `true` when the server
- * answers with a 2xx, `false` on any error or non-2xx. Reused by setup's
- * `waitForInfinity`.
- */
-export declare function probeInfinityHealth(baseURL: string, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<boolean>;
-/**
- * List the model ids an Infinity server currently serves via its OpenAI-style
- * `/models` listing (`{ data: [{ id }] }`). Returns `[]` on any error.
- */
-export declare function listInfinityModels(baseURL: string, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<string[]>;
 /**
  * Embedder for a local Infinity server. Inherits the OpenAI-style `/embeddings`
  * HTTP path, batching, retry, and reranker wiring from `OpenAICompatibleEmbedder`
- * unchanged — it adds ONLY container-readiness behavior (`ensureModelAvailable`),
+ * unchanged — it adds ONLY container-readiness behavior (`ensureModelAvailable`,
+ * `listModels`), delegating to the standalone `infinity-provisioning` primitive
  * because Infinity binds its model set at container startup and exposes no
  * runtime model-pull API.
  */
 export declare class InfinityEmbedder extends OpenAICompatibleEmbedder {
     private readonly base;
-    private readonly doFetchImpl;
-    private readonly runCommand;
     private readonly composePath;
-    private readonly pollIntervalMs;
-    private readonly log;
+    private readonly provisioningDeps;
     constructor(config: Config, logger?: ILogger, deps?: InfinityDeps);
-    private isHealthy;
-    private servedModels;
-    /** True when a managed compose file exists AND declares an `infinity` service. */
-    private hasManagedService;
     /**
-     * Bring the Infinity backend to a serving state per the D4 decision tree:
-     *   healthy + model served      → OK
-     *   healthy + model NOT served  → throw (restart container with correct --model-id)
-     *   unreachable + managed        → `docker compose up -d infinity`, wait /health
-     *   unreachable + external       → print manual instructions (no Docker touched)
-     *
-     * Called by `IndexCommand` before `prepareEmbeddingSchema()`.
+     * Index-time embed readiness (see `local-backend-provisioning`): verifies only
+     * the embedding model — indexing does not use the reranker, so a missing
+     * reranker model never blocks or restarts indexing. Whenever a recreate is
+     * needed, the full configured set is written so an already-served reranker
+     * model is never dropped. Called by `IndexCommand` before indexing.
      */
     ensureModelAvailable(): Promise<void>;
-    /**
-     * Poll `/health` until ready or the timeout elapses. Generous default (30 min)
-     * because a CPU first boot downloads the model set and runs a lengthy per-model
-     * warmup before `/health` flips to 200.
-     */
-    private waitForHealthy;
+    listModels(): Promise<string[]>;
 }

package/dist/src/services/InfinityEmbedder.js

@@ -33,167 +33,56 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InfinityEmbedder = void 0;
-exports.serverRoot = serverRoot;
-exports.probeInfinityHealth = probeInfinityHealth;
-exports.listInfinityModels = listInfinityModels;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
+exports.InfinityEmbedder = exports.listInfinityModels = exports.probeInfinityHealth = exports.serverRoot = void 0;
 const LoggerService_1 = require("./LoggerService");
 const config_store_1 = require("../config-store");
 const OpenAICompatibleEmbedder_1 = require("./OpenAICompatibleEmbedder");
-/**
- * Strip trailing slashes and a trailing `/embeddings` or `/v1` to get the server
- * root — Infinity serves `/health`, `/models`, `/rerank`, `/embeddings` from the
- * root, so a baseURL written with an OpenAI-style suffix must be normalized here
- * to keep the probe/models URLs aligned with the embeddings URL.
- */
-function serverRoot(baseURL) {
-    return baseURL.replace(/\/+$/, '').replace(/\/(embeddings|v1)$/, '');
-}
-/**
- * Probe an Infinity-style `/health` endpoint. Resolves `true` when the server
- * answers with a 2xx, `false` on any error or non-2xx. Reused by setup's
- * `waitForInfinity`.
- */
-async function probeInfinityHealth(baseURL, fetchImpl = fetch, timeoutMs = 2000) {
-    try {
-        const res = await fetchImpl(`${serverRoot(baseURL)}/health`, {
-            method: 'GET',
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        return res.ok;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * List the model ids an Infinity server currently serves via its OpenAI-style
- * `/models` listing (`{ data: [{ id }] }`). Returns `[]` on any error.
- */
-async function listInfinityModels(baseURL, fetchImpl = fetch, timeoutMs = 5000) {
-    try {
-        const res = await fetchImpl(`${serverRoot(baseURL)}/models`, {
-            method: 'GET',
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        if (!res.ok)
-            return [];
-        const data = await res.json();
-        return (data.data ?? []).map(m => m.id).filter((id) => Boolean(id));
-    }
-    catch {
-        return [];
-    }
-}
+const infinity_provisioning_1 = require("./infinity-provisioning");
+Object.defineProperty(exports, "serverRoot", { enumerable: true, get: function () { return infinity_provisioning_1.serverRoot; } });
+Object.defineProperty(exports, "probeInfinityHealth", { enumerable: true, get: function () { return infinity_provisioning_1.probeInfinityHealth; } });
+Object.defineProperty(exports, "listInfinityModels", { enumerable: true, get: function () { return infinity_provisioning_1.listInfinityModels; } });
+const path = __importStar(require("path"));
 /**
  * Embedder for a local Infinity server. Inherits the OpenAI-style `/embeddings`
  * HTTP path, batching, retry, and reranker wiring from `OpenAICompatibleEmbedder`
- * unchanged — it adds ONLY container-readiness behavior (`ensureModelAvailable`),
+ * unchanged — it adds ONLY container-readiness behavior (`ensureModelAvailable`,
+ * `listModels`), delegating to the standalone `infinity-provisioning` primitive
  * because Infinity binds its model set at container startup and exposes no
  * runtime model-pull API.
  */
 class InfinityEmbedder extends OpenAICompatibleEmbedder_1.OpenAICompatibleEmbedder {
     base;
-    doFetchImpl;
-    runCommand;
     composePath;
-    pollIntervalMs;
-    log;
+    provisioningDeps;
     constructor(config, logger = LoggerService_1.LoggerService.silent(), deps = {}) {
         super(config, logger, deps);
-        this.base = serverRoot(config.embedding.baseURL);
-        this.doFetchImpl = deps.fetchImpl ?? fetch;
-        this.runCommand = deps.runCommand ?? ((cmd, args, env) => {
-            const r = (0, child_process_1.spawnSync)(cmd, args, { stdio: 'inherit', env: env ? { ...process.env, ...env } : process.env });
-            return { status: r.status, stdout: r.stdout?.toString() };
-        });
+        this.base = (0, infinity_provisioning_1.serverRoot)(config.embedding.baseURL);
         this.composePath = deps.composePath ?? path.join(config_store_1.CONFIG_DIR, 'docker-compose.yml');
-        this.pollIntervalMs = deps.pollIntervalMs ?? 2000;
-        this.log = logger;
-    }
-    isHealthy() {
-        return probeInfinityHealth(this.base, this.doFetchImpl);
-    }
-    servedModels() {
-        return listInfinityModels(this.base, this.doFetchImpl);
-    }
-    /** True when a managed compose file exists AND declares an `infinity` service. */
-    hasManagedService() {
-        try {
-            const content = fs.readFileSync(this.composePath, 'utf-8');
-            return /^\s*infinity:\s*$/m.test(content);
-        }
-        catch {
-            return false;
-        }
+        this.provisioningDeps = {
+            fetchImpl: deps.fetchImpl,
+            runCommand: deps.runCommand,
+            pollIntervalMs: deps.pollIntervalMs,
+            readinessTimeoutMs: deps.readinessTimeoutMs,
+        };
     }
     /**
-     * Bring the Infinity backend to a serving state per the D4 decision tree:
-     *   healthy + model served      → OK
-     *   healthy + model NOT served  → throw (restart container with correct --model-id)
-     *   unreachable + managed        → `docker compose up -d infinity`, wait /health
-     *   unreachable + external       → print manual instructions (no Docker touched)
-     *
-     * Called by `IndexCommand` before `prepareEmbeddingSchema()`.
+     * Index-time embed readiness (see `local-backend-provisioning`): verifies only
+     * the embedding model — indexing does not use the reranker, so a missing
+     * reranker model never blocks or restarts indexing. Whenever a recreate is
+     * needed, the full configured set is written so an already-served reranker
+     * model is never dropped. Called by `IndexCommand` before indexing.
      */
     async ensureModelAvailable() {
-        const model = this.config.embedding.model;
-        if (await this.isHealthy()) {
-            const served = await this.servedModels();
-            // A server that lists no models (older Infinity, or listing disabled) is
-            // trusted — the embed request will surface a real error if the model is
-            // truly absent.
-            if (served.length === 0 || served.includes(model))
-                return;
-            throw new Error(`Infinity at ${this.base} serves [${served.join(', ')}] but embedding.model is "${model}". ` +
-                `Restart the container with the correct --model-id (e.g. recreate the managed container ` +
-                `via rag-setup, or fix embedding.model).`);
-        }
-        // Unreachable.
-        if (this.hasManagedService()) {
-            console.log(`Infinity not reachable at ${this.base} — starting the managed container...`);
-            this.log.info('InfinityEmbedder: starting managed container', { composePath: this.composePath });
-            // Bind the SAME model set the config expects (embed + reranker when enabled),
-            // so the auto-started container matches the config — otherwise compose would
-            // (re)create it with the compose default and silently drop the reranker /
-            // serve the wrong embed model. `--force-recreate` picks up a changed set.
-            const modelIds = [
-                this.config.embedding.model,
-                ...(this.config.reranker.enabled && this.config.reranker.model ? [this.config.reranker.model] : []),
-            ].join(';');
-            const r = this.runCommand('docker', ['compose', '-f', this.composePath, 'up', '-d', '--force-recreate', 'infinity'], { INFINITY_MODEL_ID: modelIds });
-            if (r.status !== 0) {
-                throw new Error(`Failed to start the managed Infinity container (docker compose exited ${r.status}). ` +
-                    `Ensure Docker is running, or start Infinity manually.`);
-            }
-            await this.waitForHealthy();
-            return;
-        }
-        throw new Error(`Infinity is not reachable at ${this.base} and no managed container is configured. ` +
-            `Start it manually, e.g.:\n` +
-            `  docker run -it --gpus all -p 7997:7997 michaelf34/infinity:latest \\\n` +
-            `    v2 --model-id ${model} --port 7997\n` +
-            `(drop --gpus all to run on CPU), or re-run rag-setup to provision it.`);
+        await (0, infinity_provisioning_1.ensureBackendReady)({
+            baseURL: this.config.embedding.baseURL,
+            requiredModels: [this.config.embedding.model],
+            modelSetToWrite: (0, infinity_provisioning_1.requiredModelSet)(this.config),
+            composePath: this.composePath,
+            deps: this.provisioningDeps,
+        });
     }
-    /**
-     * Poll `/health` until ready or the timeout elapses. Generous default (30 min)
-     * because a CPU first boot downloads the model set and runs a lengthy per-model
-     * warmup before `/health` flips to 200.
-     */
-    async waitForHealthy(maxWaitSec = 1800) {
-        console.log('Waiting for Infinity to be ready (first boot downloads + warms up the model set, this can take several minutes on CPU)...');
-        const deadline = Date.now() + maxWaitSec * 1000;
-        while (Date.now() < deadline) {
-            if (await this.isHealthy()) {
-                console.log('  ✓ Infinity ready.');
-                return;
-            }
-            await new Promise(r => setTimeout(r, this.pollIntervalMs));
-        }
-        throw new Error(`Infinity did not become ready within ${maxWaitSec}s at ${this.base}.`);
+    async listModels() {
+        return (0, infinity_provisioning_1.listInfinityModels)(this.base, this.provisioningDeps.fetchImpl ?? fetch, 2000);
     }
 }
 exports.InfinityEmbedder = InfinityEmbedder;

package/dist/src/services/LoggerService.d.ts

@@ -3,7 +3,8 @@ import type { ILogger } from '../interfaces/ILogger';
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export declare class LoggerService implements ILogger {
     private readonly logger;
-    constructor(logger: pino.Logger);
+    private readonly metricsLogger;
+    constructor(logger: pino.Logger, metricsLogger?: pino.Logger | null);
     static silent(): LoggerService;
     static fromConfig(cfg: {
         level: string;
@@ -14,4 +15,5 @@ export declare class LoggerService implements ILogger {
     info(msg: string, data?: Record<string, unknown>): void;
     warn(msg: string, data?: Record<string, unknown>): void;
     error(msg: string, data?: Record<string, unknown>): void;
+    metric(msg: string, data?: Record<string, unknown>): void;
 }

package/dist/src/services/LoggerService.js

@@ -44,8 +44,13 @@ const fs = __importStar(require("fs"));
 const DEFAULT_LOG_DIR = path.join(os.homedir(), '.config', 'codesearch-mcp', 'logs');
 class LoggerService {
     logger;
-    constructor(logger) {
+    // Dedicated `info`-level channel for search telemetry, independent of the
+    // main logger's configured level. Null when file logging is disabled so
+    // metrics never reach stdout (owned by the MCP JSON transport).
+    metricsLogger;
+    constructor(logger, metricsLogger = null) {
         this.logger = logger;
+        this.metricsLogger = metricsLogger;
     }
     static silent() {
         return new LoggerService((0, pino_1.default)({ level: 'silent' }));
@@ -66,6 +71,10 @@ class LoggerService {
     static buildFromPath(level, filePath) {
         if (filePath)
             fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        // The transport target must accept `info` so the metrics channel can emit
+        // even when the main level is `warn`/`error`; the main logger still gates
+        // normal calls at `level`, so nothing else leaks below it.
+        const targetLevel = pino_1.default.levels.values[level] < pino_1.default.levels.values.info ? level : 'info';
         const transport = filePath
             ? pino_1.default.transport({
                 targets: [{
@@ -79,18 +88,23 @@ class LoggerService {
                             limit: { count: 30 },
                             size: '50m',
                         },
-                        level,
+                        level: targetLevel,
                     }],
             })
             : undefined;
         const logger = transport
             ? (0, pino_1.default)({ level }, transport)
             : (0, pino_1.default)({ level: 'silent' });
-        return new LoggerService(logger);
+        // Child logger pinned at `info` regardless of the parent level; only used by
+        // metric(). Null when there is no file transport (default stdout must stay
+        // clean for the MCP transport).
+        const metricsLogger = transport ? logger.child({}, { level: 'info' }) : null;
+        return new LoggerService(logger, metricsLogger);
     }
     debug(msg, data) { this.logger.debug(data ?? {}, msg); }
     info(msg, data) { this.logger.info(data ?? {}, msg); }
     warn(msg, data) { this.logger.warn(data ?? {}, msg); }
     error(msg, data) { this.logger.error(data ?? {}, msg); }
+    metric(msg, data) { this.metricsLogger?.info(data ?? {}, msg); }
 }
 exports.LoggerService = LoggerService;

package/dist/src/services/SearcherService.d.ts

@@ -106,11 +106,25 @@ export declare class SearcherService {
     /**
      * 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` (un-migrated DB / not yet indexed) does not block.
+     * 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`.
      */
     assertIndexMatches(): Promise<void>;
+    private compareIndexed;
     listProjects(): Promise<ProjectRow[]>;
     searchChunks(query: string, limit: number, project: string | null, threshold?: number): Promise<SearchResult[]>;
+    /**
+     * 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.
+     */
+    private emitSearchMetrics;
     fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
     fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
     getDependencies(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;

package/dist/src/services/SearcherService.js

@@ -40,11 +40,13 @@ const readline = __importStar(require("readline"));
 const child_process_1 = require("child_process");
 const file_utils_1 = require("../file-utils");
 const MonorepoAwareDiscoveryService_1 = require("./MonorepoAwareDiscoveryService");
+const legacy_ollama_index_1 = require("./legacy-ollama-index");
 const SILENT_LOGGER = {
     debug() { },
     info() { },
     warn() { },
     error() { },
+    metric() { },
 };
 const EMPTY_META = { description: null, stack: null, notes: null, relations: null };
 const GREP_MAX_RESULTS = 200;
@@ -136,15 +138,28 @@ class SearcherService {
     /**
      * 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` (un-migrated DB / not yet indexed) does not block.
+     * 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)
+        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);
+        }
+    }
+    compareIndexed(indexedProvider, indexedModel, indexedDimensions) {
         const { provider, model } = this.config.embedding;
-        if (meta.provider !== provider || meta.model !== model) {
-            throw new Error(`Index was built with ${meta.provider}/${meta.model} but the config selects ${provider}/${model}. ` +
+        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.`);
         }
         // Same model but a changed dimension (e.g. a Matryoshka `embedding.dimensions`
@@ -152,9 +167,12 @@ class SearcherService {
         // 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 (dim > 0 && dim !== meta.dimensions) {
-            throw new Error(`Index was built at ${meta.dimensions} dimensions but ${provider}/${model} now resolves to ${dim}. ` +
+        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.`);
         }
     }
@@ -173,48 +191,112 @@ class SearcherService {
         const t0 = Date.now();
         await this.assertIndexMatches();
         const effectiveThreshold = threshold ?? this.config.search.similarityThreshold;
-        const fetchLimit = this.embedder.rerank
-            ? Math.min(limit * this.config.reranker.overfetch, 200)
+        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 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;
         this.logger.debug('SearcherService: searchChunks', {
             query: query.slice(0, 120), limit, fetchLimit, project, threshold: effectiveThreshold,
         });
+        const tEmbed0 = Date.now();
         const embedding = await this.embedder.embed(query, 'query');
-        const params = [`[${embedding}]`, effectiveThreshold, fetchLimit];
+        const embedMs = Date.now() - tEmbed0;
+        const params = [`[${embedding}]`, effectiveThreshold, dbLimit];
         let projectFilter = '';
         if (project) {
             params.push(project);
             projectFilter = `AND "serviceName" = $${params.length}`;
         }
-        const candidates = await this.db.query(`SELECT "serviceName", "filePath", "startLine", content, "ownerPath",
+        const tDb0 = Date.now();
+        const fetched = await this.db.query(`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;
+        // 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;
+        const candidates = fetched.slice(0, fetchLimit);
         this.logger.debug('SearcherService: searchChunks candidates', {
             count: candidates.length,
             scores: candidates.map(r => r.score),
             files: candidates.map(r => r.filePath),
             ms: Date.now() - t0,
         });
-        if (!this.embedder.rerank || candidates.length === 0)
-            return candidates;
-        try {
-            const indices = await this.embedder.rerank(query, candidates.map(r => r.content), limit);
-            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.
-            return indices.filter(i => i >= 0 && i < candidates.length).slice(0, limit).map(i => candidates[i]);
+        let results;
+        let rerankMs = 0;
+        if (!reranking || candidates.length === 0) {
+            results = candidates.slice(0, limit);
+        }
+        else {
+            const tRerank0 = Date.now();
+            try {
+                const indices = await this.embedder.rerank(query, candidates.map(r => r.content), limit);
+                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]);
+            }
+            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),
+                    ms: Date.now() - t0,
+                });
+                results = candidates.slice(0, limit);
+            }
         }
-        catch (err) {
-            this.logger.warn('SearcherService: rerank failed, falling back to vector order', {
-                reason: err instanceof Error ? err.message : String(err),
-                ms: Date.now() - t0,
+        if (metricsOn) {
+            this.emitSearchMetrics(query, {
+                fetchLimit, candidates, results, poolSaturated, embedMs, dbMs, rerankMs, totalMs: Date.now() - t0,
             });
-            return candidates.slice(0, limit);
         }
+        return results;
+    }
+    /**
+     * 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]));
+        const maxCosineRankSurvived = results.reduce((max, r) => Math.max(max, contentIndex.get(r) ?? -1), -1);
+        const fileCounts = new Map();
+        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', {
+            query: query.slice(0, 120),
+            fetchLimit: m.fetchLimit,
+            candidatesReturned: candidates.length,
+            poolSaturated: m.poolSaturated,
+            maxCosineRankSurvived,
+            resultCount: results.length,
+            distinctFilesInResult: fileCounts.size,
+            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,
+            embedMs: m.embedMs,
+            rerankMs: m.rerankMs,
+            dbMs: m.dbMs,
+            totalMs: m.totalMs,
+        });
     }
     async fetchNeighbors(results) {
         const t0 = Date.now();