lmgrep 0.1.18 → 0.2.0

package/dist/application/research/ResearchAgent.js

@@ -0,0 +1,201 @@
+import { CitationMarkers, } from "../../domain/research/Citation.js";
+import { EvidenceLedger } from "../../domain/research/EvidenceLedger.js";
+import { ResearchTrace, } from "../../domain/research/ResearchTrace.js";
+import { SearchCriteria, } from "../search/SearchCriteria.js";
+import { ResearchPrompts } from "./ResearchPrompts.js";
+/**
+ * Answers a question by searching the codebase and synthesizing a cited answer.
+ *
+ * Robustness is layered, because a local model fails in several distinct ways
+ * and none of them should hard-fail the caller:
+ *
+ *  1. Happy path — the model self-terminates with a cited answer.
+ *  2. It cannot self-terminate (step cap, timeout, or the transcript overflows
+ *     its context) — synthesize from a budgeted digest in a fresh context.
+ *  3. It answered without ever searching — discard that, since it is ungrounded
+ *     by construction, search directly and synthesize.
+ *  4. The model is unreachable — degrade to raw search hits.
+ */
+export class ResearchAgent {
+    searcher;
+    chat;
+    config;
+    static DEFAULT_MAX_STEPS = 8;
+    /**
+     * Wall clock is only a backstop against a wedged run; the search and step
+     * budgets bound the real work. A local model doing a few steps plus a cold
+     * load can need minutes, so this stays generous.
+     */
+    static DEFAULT_TIMEOUT_MS = 240_000;
+    static MAX_SEARCHES = 8;
+    static DEFAULT_SEARCH_LIMIT = 5;
+    /** The model tends to ask for 10+, which bloats the transcript. */
+    static MAX_SEARCH_LIMIT = 6;
+    /** After this many searches, nudge it to wrap up. */
+    static NUDGE_AFTER = 3;
+    constructor(searcher, chat, config) {
+        this.searcher = searcher;
+        this.chat = chat;
+        this.config = config;
+    }
+    async research(question, onTrace) {
+        if (!this.chat.isConfigured) {
+            throw new Error("`lmgrep ask` requires a chat model. Set `chatModel` in your lmgrep config " +
+                "(e.g. `chatModel: lmstudio:qwen/qwen3.5-9b`).");
+        }
+        const started = Date.now();
+        const trace = new ResearchTrace(onTrace);
+        const ledger = new EvidenceLedger();
+        const timeoutMs = this.config.chatTimeoutMs ?? ResearchAgent.DEFAULT_TIMEOUT_MS;
+        const maxSteps = this.config.chatMaxSteps ?? ResearchAgent.DEFAULT_MAX_STEPS;
+        let searchCount = 0;
+        const runSearch = async (call) => {
+            if (searchCount >= ResearchAgent.MAX_SEARCHES) {
+                return ResearchPrompts.BUDGET_EXHAUSTED;
+            }
+            searchCount++;
+            const hits = await this.runSearch(call.query, {
+                limit: Math.min(call.limit ?? ResearchAgent.DEFAULT_SEARCH_LIMIT, ResearchAgent.MAX_SEARCH_LIMIT),
+                filePrefix: call.filePrefix,
+                type: call.type,
+                language: call.language,
+            });
+            trace.searched(call.query, hits.length);
+            if (hits.isEmpty) {
+                return `No results for "${call.query}". Try different wording or a broader query.`;
+            }
+            const blocks = ledger
+                .ingest(hits.toArray())
+                .map(({ id, hit, body }) => `[${id}] ${hit.location} · ${hit.type} ${hit.name} · score ${hit.score.toFixed(2)}\n${body}`);
+            const parts = [`Results for "${call.query}":`, ...blocks];
+            if (searchCount >= ResearchAgent.NUDGE_AFTER) {
+                parts.push(ResearchPrompts.WRAP_UP);
+            }
+            return parts.join("\n\n");
+        };
+        const outcome = await this.chat.runToolLoop({
+            system: ResearchPrompts.SYSTEM,
+            prompt: question,
+            maxSteps,
+            timeoutMs,
+            toolDescription: ResearchPrompts.SEARCH_TOOL,
+            onSearch: runSearch,
+        });
+        const steps = outcome.steps;
+        let answer = outcome.status === "completed" ? outcome.text : "";
+        if (outcome.status === "failed") {
+            return this.degrade(question, outcome.error, trace, steps, started);
+        }
+        if (outcome.status === "interrupted") {
+            trace.noted(outcome.reason === "timeout"
+                ? `Timed out after ${timeoutMs}ms`
+                : "Model context exceeded mid-loop — synthesizing from gathered evidence.");
+        }
+        // The provider cannot be made to force a tool call (LM Studio ignores
+        // toolChoice), so the model sometimes answers from prior knowledge. An
+        // answer with no search behind it is ungrounded by construction —
+        // discard it and ground the question directly.
+        if (searchCount === 0) {
+            trace.noted("Model answered without searching — grounding from a direct search.");
+            try {
+                const hits = await this.runSearch(question, {
+                    limit: ResearchAgent.DEFAULT_SEARCH_LIMIT,
+                });
+                trace.searched(question, hits.length);
+                ledger.ingest(hits.toArray());
+            }
+            catch (err) {
+                return this.degrade(question, err, trace, steps, started);
+            }
+            answer = "";
+        }
+        if (!answer) {
+            answer =
+                (await this.synthesize(question, ledger, trace, timeoutMs)) ?? "";
+        }
+        if (!answer) {
+            return this.degrade(question, new Error("Model produced no answer."), trace, steps, started);
+        }
+        // Small models drop [n] markers inconsistently on terse answers. One
+        // cheap annotation pass beats returning an uncitable result.
+        if (!CitationMarkers.present(answer) && !ledger.isEmpty) {
+            answer = await this.addCitations(answer, ledger, trace, timeoutMs);
+        }
+        return {
+            question,
+            answer,
+            sources: CitationMarkers.resolve(answer, ledger.sources),
+            trace: trace.toArray(),
+            steps,
+            elapsedMs: Date.now() - started,
+            degraded: false,
+        };
+    }
+    runSearch(query, options) {
+        return this.searcher.search(query, new SearchCriteria(options));
+    }
+    /**
+     * One-shot synthesis over a budgeted digest, in a fresh context with no
+     * tool transcript to replay — which is what makes it work even when the
+     * agentic loop overflowed the window.
+     */
+    async synthesize(question, ledger, trace, timeoutMs) {
+        if (ledger.isEmpty)
+            return undefined;
+        trace.noted("Synthesizing answer from evidence…");
+        return this.chat.complete({
+            system: ResearchPrompts.SYSTEM,
+            prompt: `Question: ${question}\n\nEvidence gathered from the codebase:\n\n` +
+                `${ledger.digest()}\n\n${ResearchPrompts.FORCE_ANSWER}`,
+            timeoutMs,
+        });
+    }
+    /** Ask the model to insert markers into its own answer, wording unchanged. */
+    async addCitations(answer, ledger, trace, timeoutMs) {
+        trace.noted("Answer had no citations — adding them.");
+        const revised = await this.chat.complete({
+            system: ResearchPrompts.ADD_CITATIONS,
+            prompt: `Sources:\n${ledger.menu()}\n\nAnswer to annotate:\n${answer}`,
+            timeoutMs,
+        });
+        // Keep the original if the retry failed or still has no markers.
+        return revised && CitationMarkers.present(revised) ? revised : answer;
+    }
+    /** Last resort: return the raw hits, clearly marked as un-synthesized. */
+    async degrade(question, error, trace, steps, started) {
+        const message = error instanceof Error ? error.message : String(error);
+        trace.noted(`Synthesis unavailable: ${message}`);
+        let sources = [];
+        let body;
+        try {
+            const hits = await this.runSearch(question, {
+                limit: ResearchAgent.DEFAULT_SEARCH_LIMIT,
+            });
+            const list = hits.toArray();
+            sources = list.map((hit, i) => ({
+                n: i + 1,
+                path: hit.location.filePath,
+                startLine: hit.location.startLine,
+                endLine: hit.location.endLine,
+            }));
+            body = list.length
+                ? list
+                    .map((hit, i) => `[${i + 1}] ${hit.location} (${hit.type} ${hit.name})`)
+                    .join("\n")
+                : "No results found.";
+        }
+        catch {
+            body = "No results found (search also failed).";
+        }
+        return {
+            question,
+            answer: `Synthesis unavailable (${message}). Raw search results:\n${body}`,
+            sources,
+            trace: trace.toArray(),
+            steps,
+            elapsedMs: Date.now() - started,
+            degraded: true,
+        };
+    }
+}
+//# sourceMappingURL=ResearchAgent.js.map

package/dist/application/research/ResearchAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResearchAgent.js","sourceRoot":"","sources":["../../../src/application/research/ResearchAgent.ts"],"names":[],"mappings":"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"}

package/dist/application/research/ResearchPrompts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The instructions given to the research model.
+ *
+ * Tuned against small local models, which is why they are unusually blunt
+ * about stopping: left to themselves these models keep searching for
+ * completeness, and every extra step costs seconds.
+ */
+export declare class ResearchPrompts {
+    static readonly SYSTEM: string;
+    /** How the one available tool is described to the model. */
+    static readonly SEARCH_TOOL = "Semantic code search. Returns the top matching code units, each with a [n] id, file:line, and its source. This is the only tool \u2014 answer from what it returns.";
+    static readonly FORCE_ANSWER = "Using ONLY the evidence above, write the final answer now. Cite [n] for every claim, reusing the ids shown. If the evidence is insufficient, say so plainly and list what is still missing. Do not ask to search further.";
+    static readonly ADD_CITATIONS = "You add source citations to an existing answer. Insert [n] markers after the claims each source supports, using the ids from the source list. Do not change the wording or substance otherwise. Output only the revised answer.";
+    static readonly BUDGET_EXHAUSTED = "Search budget exhausted. Stop searching and answer from what you have.";
+    static readonly WRAP_UP = "(You've searched several times \u2014 answer now from what you've gathered unless a specific detail is still missing.)";
+}

package/dist/application/research/ResearchPrompts.js

@@ -0,0 +1,34 @@
+/**
+ * The instructions given to the research model.
+ *
+ * Tuned against small local models, which is why they are unusually blunt
+ * about stopping: left to themselves these models keep searching for
+ * completeness, and every extra step costs seconds.
+ */
+export class ResearchPrompts {
+    static SYSTEM = [
+        "You are a code research assistant working inside a repository. Answer the user's question by searching the codebase and writing a concise, grounded answer.",
+        "",
+        "Tool:",
+        "- search({query, filePrefix?, type?, language?, limit?}): semantic code search. Returns the top matching code units (functions, classes, blocks), each with a [n] id, its file:line, and its source. Phrase `query` as a natural-language intent, not keywords. The returned source is what you answer from — there is no separate file-reading step.",
+        "",
+        "Method — be decisive, minimize steps (each step is slow):",
+        "- ALWAYS search before answering. Never answer from prior knowledge or assumptions — the codebase is the only source of truth, and defaults, names, and behavior often differ from what you'd guess.",
+        "- A grounded, focused answer beats an exhaustive survey. Aim to answer in as few searches as possible.",
+        "- Typical shape: one search → answer. Search again ONLY if the results revealed a specific gap, or surfaced codebase vocabulary you should follow up on with a sharper query.",
+        "- Never search for completeness, breadth, or to double-check. The moment the results let you answer, STOP searching and write the answer.",
+        "",
+        "Answer rules:",
+        '- Cite with the [n] id, never a bare file path. Every claim needs a [n]. Example: write "changes are debounced for 2s [2]", not "in scanner.ts, changes are debounced".',
+        "- Do NOT paste code blocks or quote source verbatim. Describe what the code does in your own words and cite [n].",
+        "- Be tight: what the code does, where, and how. No tours, no restating the question.",
+        "- If the results do not answer the question, say so plainly and list what's missing. Never invent file paths, line numbers, or behavior.",
+    ].join("\n");
+    /** How the one available tool is described to the model. */
+    static SEARCH_TOOL = "Semantic code search. Returns the top matching code units, each with a [n] id, file:line, and its source. This is the only tool — answer from what it returns.";
+    static FORCE_ANSWER = "Using ONLY the evidence above, write the final answer now. Cite [n] for every claim, reusing the ids shown. If the evidence is insufficient, say so plainly and list what is still missing. Do not ask to search further.";
+    static ADD_CITATIONS = "You add source citations to an existing answer. Insert [n] markers after the claims each source supports, using the ids from the source list. Do not change the wording or substance otherwise. Output only the revised answer.";
+    static BUDGET_EXHAUSTED = "Search budget exhausted. Stop searching and answer from what you have.";
+    static WRAP_UP = "(You've searched several times — answer now from what you've gathered unless a specific detail is still missing.)";
+}
+//# sourceMappingURL=ResearchPrompts.js.map

package/dist/application/research/ResearchPrompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResearchPrompts.js","sourceRoot":"","sources":["../../../src/application/research/ResearchPrompts.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAC3B,MAAM,CAAU,MAAM,GAAG;QACxB,6JAA6J;QAC7J,EAAE;QACF,OAAO;QACP,uVAAuV;QACvV,EAAE;QACF,2DAA2D;QAC3D,sMAAsM;QACtM,wGAAwG;QACxG,+KAA+K;QAC/K,2IAA2I;QAC3I,EAAE;QACF,eAAe;QACf,yKAAyK;QACzK,kHAAkH;QAClH,sFAAsF;QACtF,0IAA0I;KAC1I,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,4DAA4D;IAC5D,MAAM,CAAU,WAAW,GAC1B,gKAAgK,CAAC;IAElK,MAAM,CAAU,YAAY,GAC3B,2NAA2N,CAAC;IAE7N,MAAM,CAAU,aAAa,GAC5B,iOAAiO,CAAC;IAEnO,MAAM,CAAU,gBAAgB,GAC/B,wEAAwE,CAAC;IAE1E,MAAM,CAAU,OAAO,GACtB,mHAAmH,CAAC"}

package/dist/application/search/SearchCriteria.d.ts

@@ -0,0 +1,37 @@
+import type { Hit } from "../../domain/retrieval/Hit.js";
+/** Everything a caller can ask of a search. */
+export interface SearchOptions {
+    limit?: number;
+    filePrefix?: string;
+    /** Push results away from this meaning. */
+    not?: string;
+    minScore?: number;
+    /** Only chunks of these AST types. */
+    type?: string[];
+    /** Only files with these extensions (".ts", ".py"). */
+    language?: string[];
+    /** Search another project's index instead of this one. */
+    project?: string;
+    /** Search several project indexes and merge by score. */
+    across?: string[];
+}
+/**
+ * A search request, with the filters that can only be applied after retrieval.
+ *
+ * Language and score filters live here rather than in the query because
+ * neither is stored in a form the vector index can filter on: extensions are a
+ * property of the path, and scores only exist once distances are computed.
+ */
+export declare class SearchCriteria {
+    private readonly options;
+    static readonly DEFAULT_LIMIT = 25;
+    private readonly extensions;
+    constructor(options: SearchOptions);
+    get limit(): number;
+    get filePrefix(): string | undefined;
+    get types(): string[] | undefined;
+    get negation(): string | undefined;
+    get project(): string | undefined;
+    get across(): string[] | undefined;
+    admits(hit: Hit): boolean;
+}

package/dist/application/search/SearchCriteria.js

@@ -0,0 +1,48 @@
+/**
+ * A search request, with the filters that can only be applied after retrieval.
+ *
+ * Language and score filters live here rather than in the query because
+ * neither is stored in a form the vector index can filter on: extensions are a
+ * property of the path, and scores only exist once distances are computed.
+ */
+export class SearchCriteria {
+    options;
+    static DEFAULT_LIMIT = 25;
+    extensions;
+    constructor(options) {
+        this.options = options;
+        const languages = options.language;
+        this.extensions =
+            languages && languages.length > 0
+                ? new Set(languages.map((l) => (l.startsWith(".") ? l : `.${l}`)))
+                : undefined;
+    }
+    get limit() {
+        return this.options.limit ?? SearchCriteria.DEFAULT_LIMIT;
+    }
+    get filePrefix() {
+        return this.options.filePrefix;
+    }
+    get types() {
+        return this.options.type;
+    }
+    get negation() {
+        return this.options.not;
+    }
+    get project() {
+        return this.options.project;
+    }
+    get across() {
+        return this.options.across;
+    }
+    admits(hit) {
+        if (this.extensions && !this.extensions.has(hit.location.extension)) {
+            return false;
+        }
+        if (this.options.minScore != null && hit.score < this.options.minScore) {
+            return false;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=SearchCriteria.js.map

package/dist/application/search/SearchCriteria.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchCriteria.js","sourceRoot":"","sources":["../../../src/application/search/SearchCriteria.ts"],"names":[],"mappings":"AAmBA;;;;;;GAMG;AACH,MAAM,OAAO,cAAc;IAKG;IAJ7B,MAAM,CAAU,aAAa,GAAG,EAAE,CAAC;IAElB,UAAU,CAA0B;IAErD,YAA6B,OAAsB;QAAtB,YAAO,GAAP,OAAO,CAAe;QAClD,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;QACnC,IAAI,CAAC,UAAU;YACd,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;gBAChC,CAAC,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;gBAClE,CAAC,CAAC,SAAS,CAAC;IACf,CAAC;IAED,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC,aAAa,CAAC;IAC3D,CAAC;IAED,IAAI,UAAU;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;IAChC,CAAC;IAED,IAAI,KAAK;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED,IAAI,QAAQ;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;IACzB,CAAC;IAED,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,GAAQ;QACd,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACrE,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YACxE,OAAO,KAAK,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC"}

package/dist/application/search/SearchService.d.ts

@@ -0,0 +1,36 @@
+import type { LmgrepConfig } from "../../domain/config/LmgrepConfig.js";
+import type { EmbedderPort } from "../../domain/ports/EmbedderPort.js";
+import type { LoggerPort } from "../../domain/ports/LoggerPort.js";
+import type { IndexMetadata } from "../../domain/project/IndexMetadata.js";
+import { HitList } from "../../domain/retrieval/HitList.js";
+import type { IndexAlternatives } from "../operations/IndexAlternatives.js";
+import type { SearchCriteria } from "./SearchCriteria.js";
+import type { SearchTargetResolver } from "./SearchTargetResolver.js";
+/**
+ * Runs a semantic search: embed the query, retrieve from every target index,
+ * merge, and apply the filters retrieval cannot.
+ */
+export declare class SearchService {
+    private readonly embedder;
+    private readonly targets;
+    private readonly config;
+    private readonly logger;
+    private readonly readMetadata;
+    private readonly alternatives;
+    /**
+     * How strongly a `--not` query pushes results away. Full subtraction
+     * overshoots into unrelated space; half keeps the original intent dominant
+     * while still displacing the unwanted sense.
+     */
+    private static readonly NEGATION_WEIGHT;
+    constructor(embedder: EmbedderPort, targets: SearchTargetResolver, config: LmgrepConfig, logger: LoggerPort, readMetadata: () => IndexMetadata | undefined, alternatives: IndexAlternatives);
+    search(query: string, criteria: SearchCriteria): Promise<HitList>;
+    private retrieveFrom;
+    private buildQueryVector;
+    /**
+     * A width mismatch is fatal — the vectors are simply incomparable. A family
+     * mismatch is only a warning: results degrade rather than break, and the
+     * user may have deliberately swapped a compatible model.
+     */
+    private verifyModelCompatibility;
+}

package/dist/application/search/SearchService.js

@@ -0,0 +1,108 @@
+import { ModelIdentity } from "../../domain/project/ModelIdentity.js";
+import { HitList } from "../../domain/retrieval/HitList.js";
+import { MissingIndexError } from "../../domain/retrieval/MissingIndexError.js";
+/**
+ * Runs a semantic search: embed the query, retrieve from every target index,
+ * merge, and apply the filters retrieval cannot.
+ */
+export class SearchService {
+    embedder;
+    targets;
+    config;
+    logger;
+    readMetadata;
+    alternatives;
+    /**
+     * How strongly a `--not` query pushes results away. Full subtraction
+     * overshoots into unrelated space; half keeps the original intent dominant
+     * while still displacing the unwanted sense.
+     */
+    static NEGATION_WEIGHT = 0.5;
+    constructor(embedder, targets, config, logger, readMetadata, alternatives) {
+        this.embedder = embedder;
+        this.targets = targets;
+        this.config = config;
+        this.logger = logger;
+        this.readMetadata = readMetadata;
+        this.alternatives = alternatives;
+    }
+    async search(query, criteria) {
+        const queryVector = await this.buildQueryVector(query, criteria);
+        const targets = await this.targets.resolve(criteria);
+        try {
+            const merged = await this.retrieveFrom(targets, queryVector, criteria);
+            return merged.filtered((hit) => criteria.admits(hit));
+        }
+        catch (err) {
+            // "No index found" is accurate and useless on its own: the usual
+            // cause is a model change, and the index the user is thinking of is
+            // intact one directory away.
+            if (err instanceof MissingIndexError) {
+                const absence = this.alternatives.explainAbsence();
+                if (absence) {
+                    throw new MissingIndexError(`${absence.reason}\n${absence.fix}`);
+                }
+            }
+            throw err;
+        }
+        finally {
+            await this.targets.release(targets);
+        }
+    }
+    async retrieveFrom(targets, queryVector, criteria) {
+        let merged = HitList.empty();
+        for (const target of targets) {
+            const page = await target.chunks.search({
+                vector: queryVector,
+                limit: criteria.limit,
+                filePrefix: target.filePrefix,
+                types: criteria.types,
+                // A foreign index has no manifest for our branch, so scoping to
+                // it would filter everything away.
+                scopeToBranch: target.projectRoot === undefined,
+            });
+            merged = merged.concat(target.projectRoot
+                ? page.mapped((hit) => hit.relocatedUnder(target.projectRoot))
+                : page);
+        }
+        // Scores are comparable across indexes only when the same model built
+        // them; re-sorting is still the best available merge.
+        return targets.length > 1
+            ? merged.sortedByScoreDescending().takeAtMost(criteria.limit)
+            : merged;
+    }
+    async buildQueryVector(query, criteria) {
+        const vector = await this.embedder.embedQuery(query);
+        this.verifyModelCompatibility(vector);
+        const negation = criteria.negation;
+        if (!negation)
+            return vector;
+        const away = await this.embedder.embedQuery(negation);
+        return vector.minus(away.scaledBy(SearchService.NEGATION_WEIGHT));
+    }
+    /**
+     * A width mismatch is fatal — the vectors are simply incomparable. A family
+     * mismatch is only a warning: results degrade rather than break, and the
+     * user may have deliberately swapped a compatible model.
+     */
+    verifyModelCompatibility(queryVector) {
+        const meta = this.readMetadata();
+        if (!meta)
+            return;
+        if (meta.dimensions != null && queryVector.dimensions !== meta.dimensions) {
+            throw new Error(`Dimension mismatch: index has ${meta.dimensions}-dim vectors but ` +
+                `your model produces ${queryVector.dimensions}-dim. ` +
+                "These embeddings are incompatible.");
+        }
+        if (!meta.model)
+            return;
+        const indexModel = ModelIdentity.of(meta.model);
+        const queryModel = ModelIdentity.of(this.config.model);
+        if (!indexModel.isSameFamilyAs(queryModel)) {
+            this.logger.info(`Warning: index was built with "${meta.model}" (${indexModel.family}) ` +
+                `but searching with "${this.config.model}" (${queryModel.family}). ` +
+                "Results may be degraded if these are different model families.");
+        }
+    }
+}
+//# sourceMappingURL=SearchService.js.map

package/dist/application/search/SearchService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchService.js","sourceRoot":"","sources":["../../../src/application/search/SearchService.ts"],"names":[],"mappings":"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"}

package/dist/application/search/SearchTargetResolver.d.ts

@@ -0,0 +1,56 @@
+import type { ChunkRepositoryPort } from "../../domain/ports/ChunkRepositoryPort.js";
+import type { DatabaseLocation } from "../../domain/project/DatabaseLocation.js";
+import type { ProjectLocator } from "../../domain/project/ProjectLocator.js";
+import type { SearchCriteria } from "./SearchCriteria.js";
+/** One index a search should consult. */
+export interface SearchTarget {
+    chunks: ChunkRepositoryPort;
+    filePrefix?: string;
+    /**
+     * Absolute root of a foreign project, used to make its relative paths
+     * meaningful here. Undefined for the local index.
+     */
+    projectRoot?: string;
+    /** Whether this target was opened for the query and must be closed after. */
+    borrowed: boolean;
+}
+/** Opens a chunk repository for another project's database. */
+export interface ForeignIndexOpener {
+    open(projectPath: string): Promise<{
+        chunks: ChunkRepositoryPort;
+        close: () => Promise<void>;
+    }>;
+}
+/**
+ * Decides which indexes a search reads.
+ *
+ * Three cases, in precedence order: `--across` merges several projects,
+ * `--project` redirects to one, and the default resolves the local project —
+ * including the case where the working directory sits below an indexed root,
+ * where the offset becomes a path prefix filter.
+ */
+export declare class SearchTargetResolver {
+    private readonly cwd;
+    private readonly local;
+    private readonly location;
+    private readonly locator;
+    private readonly foreign;
+    private readonly opened;
+    constructor(cwd: string, local: ChunkRepositoryPort, location: DatabaseLocation, locator: ProjectLocator, foreign: ForeignIndexOpener);
+    resolve(criteria: SearchCriteria): Promise<SearchTarget[]>;
+    /** Close the databases this resolver opened; leave the local one alone. */
+    release(targets: SearchTarget[]): Promise<void>;
+    private openForeign;
+    /**
+     * The local index, with the working directory's offset from the project
+     * root folded into the prefix filter — so searching from `src/lib` only
+     * returns hits from there. A manually targeted database is flat and skips
+     * this entirely.
+     *
+     * Inside a git repo the ancestor resolves to the same database, because
+     * project identity is the remote. Outside git the walk-up can land on a
+     * genuinely different database — an indexed parent directory — which must
+     * be opened rather than substituted with the local one.
+     */
+    private resolveLocal;
+}