@angri450/zvec-grep 0.2.2

package/dist/engine/service/zvec-grep.js

@@ -0,0 +1,1520 @@
+import { readFileSync, statSync } from "node:fs";
+import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { globalConfigPath, readGlobalConfig, resolveEmbeddingRuntimeOptions, } from "../config.js";
+import { isWorkspaceIndexed, WorkspaceIndex } from "./workspace-index.js";
+import { workspaceIndexDetail, detail, EngineError, errorDetails, } from "../errors.js";
+import { createEmbeddingModel, EmbeddingPurpose, getEmbeddingModelCatalogEntry, normalizeLocalEmbeddingConcurrency, resolveEmbeddingReference, resolveIndexEmbeddingConcurrencyOverride, } from "../models/index.js";
+import { CURRENT_INDEX_VERSION } from "../types.js";
+import { indexStatusNeedsRefresh } from "../index-status.js";
+import { workspaceIndexInfoFromManifest, CURRENT_MANIFEST_VERSION, readWorkspaceManifest, writeWorkspaceManifest, } from "../manifest.js";
+import { validateRootPaths } from "../pipeline/indexing/root-paths.js";
+import { findNearestWorkspace, hasWorkspaceIndex, resetWorkspaceIndex, resolveZvecGrepRoot, workspaceHome, workspaceIndexLocation, } from "./root.js";
+import { runRgSearch } from "./lexical.js";
+import { defaultHome, normalizePath } from "../utils/path.js";
+import { acquireReadWriteLock, assertNoWriteLock, } from "../utils/lock.js";
+import { assertDaemonWriteAllowed } from "../utils/daemon-lease.js";
+import { TimingCollector } from "../utils/timing.js";
+import { enrichLexicalItemsWithStructure } from "./structure-enrichment.js";
+import { remoteEmbeddingAuthorizationGuard } from "../../authorization/operation.js";
+import { RemoteEmbeddingAuthorizationStore } from "../../authorization/store.js";
+const DEFAULT_CONTEXT_LIMIT = 10;
+const DEFAULT_CONTEXT_TOTAL_LIMIT = 30;
+const DEFAULT_LOCAL_EMBEDDING = "local/potion-code-16m-v2";
+const PROVIDER_API_KEY_IDENTITY_SECRET = randomBytes(32);
+const MAX_RECOVERED_EMBEDDING_MODELS = 4;
+export async function createZvecGrep(options = {}) {
+    return new ZvecGrepService(options);
+}
+export function openWorkspaceReadSession(startRoot, embeddingModel) {
+    const start = resolveZvecGrepRoot(startRoot);
+    assertNearestWorkspaceHomeUnlocked(start, "daemon.context.open");
+    const nearest = findNearestWorkspaceIndex(start);
+    if (!nearest) {
+        throw workspaceIndexMissingError(start, "undecided");
+    }
+    const { location, info } = nearest;
+    if (info.indexPolicy === "disabled") {
+        throw workspaceIndexDisabledError(location.root);
+    }
+    if (!isWorkspaceIndexed(info) || !hasWorkspaceIndex(location)) {
+        throw workspaceIndexMissingError(location.root, info.indexPolicy ?? "enabled");
+    }
+    const workspaceIndex = new WorkspaceIndex(info, {
+        mode: "read",
+        embeddingModel,
+    });
+    let closed = false;
+    return {
+        root: location.root,
+        async context(options) {
+            if (closed) {
+                throw new EngineError("Workspace read session is already closed", {
+                    code: "ZVEC_GREP.ENGINE.SERVICE.READ_SESSION_CLOSED",
+                });
+            }
+            const timings = new TimingCollector();
+            const request = normalizeContextRequest(options);
+            const result = await timings.time("total", () => withHomeReadLock(location.home, "daemon.context", () => contextFromOpenWorkspaceIndex({
+                root: location.root,
+                request,
+                workspaceIndex,
+                options: { ...options, autoUpdate: false },
+                timings,
+            })));
+            return withContextTimings(result, timings);
+        },
+        async close() {
+            if (closed) {
+                return;
+            }
+            workspaceIndex.close();
+            closed = true;
+        },
+    };
+}
+export function createEmbeddingModelForIdentity(identity, options = {}, workspaceRuntime = {}) {
+    const reference = embeddingModelReference(identity);
+    return createServiceEmbeddingModel(reference, providerOptions(options, identity, readGlobalConfig(), workspaceRuntime, options.embeddingConcurrency), options);
+}
+export function embeddingModelPoolKeyForIdentity(identity, options = {}, workspaceRuntime = {}) {
+    const reference = embeddingModelReference(identity);
+    const fingerprint = providerOptionsFingerprint(providerOptions(options, identity, readGlobalConfig(), workspaceRuntime, options.embeddingConcurrency));
+    return [reference, fingerprint].join("/");
+}
+class ZvecGrepService {
+    options;
+    root;
+    embeddingModel;
+    recoveredEmbeddingModels = new Map();
+    retiredEmbeddingModels = new Set();
+    localEmbeddingVariants = new Map();
+    modelSelectionPromise = Promise.resolve();
+    modelDisposalPromise = Promise.resolve();
+    activeEmbeddingModelOperations = 0;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.root = resolveZvecGrepRoot(options.root);
+        this.embeddingModel = options.embeddingModel;
+    }
+    async index(options = {}) {
+        this.ensureOpen();
+        const root = resolveZvecGrepRoot(options.root ?? this.root);
+        const daemonWritePermit = assertDaemonWriteAllowed(root, this.options.daemonInstanceToken);
+        const location = workspaceIndexLocation(root);
+        try {
+            return await this.withEmbeddingModelOperation(() => withHomeWriteLock(location.home, options.rebuild ? "index.rebuild" : "index", async () => {
+                const existing = readWorkspaceManifest(location.home);
+                const existingRuntime = existing?.embeddingRuntime ?? {};
+                const { model: embeddingModel, concurrency: embeddingConcurrency } = await this.embeddingModelForIndex(existing, "index", existingRuntime, options.embeddingConcurrency);
+                const effectiveRuntime = effectiveEmbeddingRuntime(this.options, embeddingModel, runtimeForModelProvider(existing, embeddingModel, existingRuntime));
+                if (!options.rebuild) {
+                    assertWorkspaceEndpointMatchesCurrentRuntime(existing, existingRuntime, effectiveRuntime, "zg --index --endpoint <url> --rebuild");
+                }
+                const rootPaths = resolveIndexRootPaths(existing, options.rootPaths, root, {
+                    resetPaths: options.resetPaths === true,
+                    includePaths: options.includePaths,
+                    excludePaths: options.excludePaths,
+                    globs: options.globs,
+                    insensitiveGlobs: options.insensitiveGlobs,
+                    fileTypes: options.fileTypes,
+                    excludedFileTypes: options.excludedFileTypes,
+                    hidden: options.hidden,
+                    noIgnore: options.noIgnore,
+                    ignoreFiles: options.ignoreFiles,
+                    maxDepth: options.maxDepth,
+                    maxFileSizeBytes: options.maxFileSizeBytes,
+                    follow: options.follow,
+                });
+                if (options.rebuild || !isWorkspaceIndexed(existing)) {
+                    resetWorkspaceIndex(location);
+                }
+                const existingAfterRebuild = options.rebuild ? null : existing;
+                if (isWorkspaceIndexed(existingAfterRebuild)) {
+                    assertWorkspaceEmbeddingMatchesCurrentModel(existingAfterRebuild, embeddingModel, "zg --index --rebuild");
+                }
+                const embeddingRuntime = embeddingRuntimeAfterIndex(existing, existingRuntime, embeddingModel, effectiveRuntime, this.options);
+                const manifest = prepareWorkspaceManifest(location, existingAfterRebuild, rootPaths, embeddingModel, embeddingRuntime);
+                const workspaceIndex = new WorkspaceIndex(manifest, {
+                    mode: "write",
+                    embeddingModel,
+                });
+                writeWorkspaceManifest(location.home, manifest);
+                try {
+                    const releaseWriterContext = options.onWriterContext?.((contextOptions) => this.contextFromWriterWorkspaceIndex(root, workspaceIndex, contextOptions));
+                    try {
+                        const result = await workspaceIndex.index({
+                            rebuild: false,
+                            embeddingConcurrency,
+                            onProgress: options.onProgress,
+                            changedPaths: options.changedPaths,
+                            signal: options.signal,
+                        });
+                        writeWorkspaceManifest(location.home, {
+                            ...manifest,
+                            embeddingRuntime,
+                            updatedTime: Date.now(),
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        writeWorkspaceManifest(location.home, {
+                            ...manifest,
+                            embeddingRuntime,
+                            updatedTime: Date.now(),
+                        });
+                        throw error;
+                    }
+                    finally {
+                        await releaseWriterContext?.();
+                    }
+                }
+                finally {
+                    workspaceIndex.close();
+                }
+            }));
+        }
+        finally {
+            daemonWritePermit?.release();
+        }
+    }
+    async dropIndex(options = {}) {
+        this.ensureOpen();
+        const root = resolveZvecGrepRoot(options.root ?? this.root);
+        const daemonWritePermit = assertDaemonWriteAllowed(root, this.options.daemonInstanceToken);
+        const location = workspaceIndexLocation(root);
+        try {
+            if (!readWorkspaceManifest(location.home)) {
+                return false;
+            }
+            return await withHomeWriteLock(location.home, "index.drop", async () => {
+                resetWorkspaceIndex(location);
+                return true;
+            });
+        }
+        finally {
+            daemonWritePermit?.release();
+        }
+    }
+    async disableIndex(options = {}) {
+        this.ensureOpen();
+        const root = resolveZvecGrepRoot(options.root ?? this.root);
+        const daemonWritePermit = assertDaemonWriteAllowed(root, this.options.daemonInstanceToken);
+        const location = workspaceIndexLocation(root);
+        try {
+            await withHomeWriteLock(location.home, "index.disable", async () => {
+                const existing = readWorkspaceManifest(location.home);
+                const now = Date.now();
+                writeWorkspaceManifest(location.home, {
+                    manifestVersion: CURRENT_MANIFEST_VERSION,
+                    id: existing?.id ?? randomUUID(),
+                    name: existing?.name ?? workspaceDisplayName(root),
+                    path: location.home,
+                    rootPaths: existing?.rootPaths ?? validateRootPaths([root]),
+                    indexPolicy: "disabled",
+                    embedding: null,
+                    indexVersion: null,
+                    createdTime: existing?.createdTime ?? now,
+                    updatedTime: now,
+                    embeddingRuntime: existing?.embeddingRuntime ?? {},
+                });
+            });
+            return this.info({ root });
+        }
+        finally {
+            daemonWritePermit?.release();
+        }
+    }
+    async context(options) {
+        this.ensureOpen();
+        return await this.withEmbeddingModelOperation(async () => {
+            const timings = new TimingCollector();
+            const result = await timings.time("total", () => this.contextWithTimings(options, timings));
+            return withContextTimings(result, timings);
+        });
+    }
+    async contextWithTimings(options, timings) {
+        const request = normalizeContextRequest(options);
+        const startRoot = resolveZvecGrepRoot(options.root ?? this.root);
+        if (options.rg) {
+            return this.contextFromRg(startRoot, request, options, timings);
+        }
+        assertNearestWorkspaceHomeUnlocked(startRoot, "context");
+        const nearest = findNearestWorkspaceIndex(startRoot);
+        if (nearest) {
+            const { location, info } = nearest;
+            if (info.indexPolicy === "disabled") {
+                throw workspaceIndexDisabledError(location.root);
+            }
+            if (!isWorkspaceIndexed(info) || !hasWorkspaceIndex(location)) {
+                throw workspaceIndexMissingError(location.root, info.indexPolicy ?? "enabled");
+            }
+            if (options.autoUpdate !== false) {
+                await this.refreshWorkspaceIndexForContext(location, options, timings);
+            }
+            return await withHomeReadLock(location.home, "context", () => this.contextFromWorkspaceIndex(location, request, options, timings));
+        }
+        throw workspaceIndexMissingError(startRoot, "undecided");
+    }
+    async info(options = {}) {
+        this.ensureOpen();
+        const startRoot = resolveZvecGrepRoot(options.root ?? this.root);
+        assertNearestWorkspaceHomeUnlocked(startRoot, "info");
+        const nearest = findNearestWorkspaceIndex(startRoot);
+        if (!nearest) {
+            const location = workspaceIndexLocation(startRoot);
+            return {
+                root: startRoot,
+                indexed: false,
+                indexPolicy: "undecided",
+                home: location.home,
+                indexPath: location.indexPath,
+                source: "unindexed",
+                suggestion: "zg --index or zg --rg",
+            };
+        }
+        return await withHomeReadLock(nearest.location.home, "info", async () => {
+            const workspaceIndex = readWorkspaceManifest(nearest.location.home);
+            const indexed = workspaceIndex !== null &&
+                workspaceIndex.indexPolicy !== "disabled" &&
+                isWorkspaceIndexed(workspaceIndex) &&
+                hasWorkspaceIndex(nearest.location);
+            return {
+                root: nearest.location.root,
+                indexed,
+                indexPolicy: workspaceIndex?.indexPolicy ?? "undecided",
+                home: nearest.location.home,
+                indexPath: nearest.location.indexPath,
+                source: indexed ? "index" : "unindexed",
+                workspaceIndex: workspaceIndex
+                    ? workspaceIndexInfoFromManifest(workspaceIndex)
+                    : undefined,
+                status: indexed && options.includeStatus !== false
+                    ? await workspaceIndexStatus(workspaceIndex, nearest.location)
+                    : null,
+                suggestion: workspaceInfoSuggestion(workspaceIndex),
+            };
+        });
+    }
+    async close() {
+        this.closed = true;
+        await this.modelSelectionPromise;
+        await this.modelDisposalPromise;
+        const models = new Set([
+            ...(this.embeddingModel &&
+                this.options.embeddingModelOwnership !== "borrowed"
+                ? [this.embeddingModel]
+                : []),
+            ...this.recoveredEmbeddingModels.values(),
+            ...this.retiredEmbeddingModels,
+        ]);
+        this.recoveredEmbeddingModels.clear();
+        this.retiredEmbeddingModels.clear();
+        this.localEmbeddingVariants.clear();
+        await disposeEmbeddingModels(models);
+    }
+    async contextFromWorkspaceIndex(location, request, options, timings) {
+        const info = readWorkspaceManifest(location.home);
+        if (!info) {
+            throw new EngineError("Workspace index manifest not found", {
+                code: "ZVEC_GREP.ENGINE.MANIFEST.NOT_FOUND",
+            });
+        }
+        const workspaceIndex = await this.openWorkspaceIndexForSearch(info, request, info.embeddingRuntime);
+        try {
+            return await contextFromOpenWorkspaceIndex({
+                root: location.root,
+                request,
+                workspaceIndex,
+                options,
+                timings,
+            });
+        }
+        finally {
+            workspaceIndex.close();
+        }
+    }
+    async refreshWorkspaceIndexForContext(location, options, timings) {
+        const daemonWritePermit = assertDaemonWriteAllowed(location.root, this.options.daemonInstanceToken);
+        try {
+            const needsRefresh = await timings.time("status_scan", () => withHomeReadLock(location.home, "context.status", async () => {
+                const manifest = readWorkspaceManifest(location.home);
+                const status = manifest
+                    ? await workspaceIndexStatus(manifest, location)
+                    : null;
+                return indexStatusNeedsRefresh(status);
+            }));
+            if (!needsRefresh) {
+                return;
+            }
+            await timings.time("auto_update", () => withHomeWriteLock(location.home, "context.refresh", async () => {
+                const existing = readWorkspaceManifest(location.home);
+                if (!existing) {
+                    return;
+                }
+                const stillNeedsRefresh = await timings.time("refresh_status_scan", () => workspaceIndexNeedsRefresh(location));
+                if (!stillNeedsRefresh) {
+                    return;
+                }
+                const workspaceRuntime = existing.embeddingRuntime;
+                const { model: embeddingModel, concurrency: embeddingConcurrency } = await this.embeddingModelForIndex(existing, "context.refresh", workspaceRuntime, options.embeddingConcurrency);
+                assertWorkspaceEndpointMatchesCurrentRuntime(existing, workspaceRuntime, effectiveEmbeddingRuntime(this.options, embeddingModel, workspaceRuntime), "zg --index --endpoint <url> --rebuild");
+                assertWorkspaceEmbeddingMatchesCurrentModel(existing, embeddingModel, "zg --index --rebuild");
+                const workspaceIndex = new WorkspaceIndex(existing, {
+                    mode: "write",
+                    embeddingModel,
+                });
+                try {
+                    const result = await workspaceIndex.index({
+                        embeddingConcurrency,
+                        onProgress: options.onAutoUpdateProgress,
+                    });
+                    timings.addEntries(result.timings, "auto_update_");
+                }
+                finally {
+                    workspaceIndex.close();
+                }
+            }));
+        }
+        finally {
+            daemonWritePermit?.release();
+        }
+    }
+    async contextFromWriterWorkspaceIndex(root, workspaceIndex, options) {
+        return await this.withEmbeddingModelOperation(async () => {
+            const timings = new TimingCollector();
+            const request = normalizeContextRequest(options);
+            const result = await timings.time("total", () => contextFromOpenWorkspaceIndex({
+                root,
+                request,
+                workspaceIndex,
+                options: { ...options, autoUpdate: false },
+                timings,
+            }));
+            return withContextTimings(result, timings);
+        });
+    }
+    async contextFromRg(root, request, options, timings) {
+        let rgResult;
+        try {
+            rgResult = await timings.time("rg_search", () => runRgSearch({
+                root,
+                patterns: request.rgPatterns,
+                paths: options.rgPaths,
+                limit: options.limit,
+                includePaths: options.includePaths,
+                excludePaths: options.excludePaths,
+                globs: options.globs,
+                insensitiveGlobs: options.insensitiveGlobs,
+                fileTypes: options.fileTypes,
+                excludedFileTypes: options.excludedFileTypes,
+                hidden: options.hidden,
+                noIgnore: options.noIgnore,
+                ignoreFiles: options.ignoreFiles,
+                maxDepth: options.maxDepth,
+                maxFileSizeBytes: options.maxFileSizeBytes,
+                follow: options.follow,
+                modifiedAfter: options.modifiedAfter,
+                modifiedBefore: options.modifiedBefore,
+                rgOptions: options.rgOptions,
+            }));
+        }
+        catch (cause) {
+            throw new EngineError("Search failed", {
+                code: "ZVEC_GREP.ENGINE.SEARCH.FAILED",
+                context: errorDetails([detail("source", "rg"), detail("root", root)]),
+                cause,
+            });
+        }
+        const structuralEnrichment = await timings.time("structure_enrichment", () => enrichLexicalItemsWithStructure(root, rgResult.items, undefined, options.maxFileSizeBytes));
+        const items = dedupeAndRerankContextItems(structuralEnrichment.items);
+        const emptyReason = items.length === 0 ? rgEmptyReason(rgResult.diagnostics) : undefined;
+        return {
+            query: request.displayQuery,
+            root,
+            source: "rg",
+            coverage: rgResult.diagnostics.truncated
+                ? "rg_truncated"
+                : "rg_exhaustive",
+            items,
+            diagnostics: {
+                emptyReason,
+                rg: rgResult.diagnostics,
+                structure: structuralEnrichment.diagnostics,
+            },
+        };
+    }
+    async openWorkspaceIndexForSearch(info, request, workspaceRuntime) {
+        return new WorkspaceIndex(info, {
+            mode: "read",
+            embeddingModel: await this.embeddingModelForSearch(indexedEmbeddingSchema(info), request, workspaceRuntime, info),
+        });
+    }
+    async embeddingModelForSearch(schema, request, workspaceRuntime, info) {
+        if (!request.routes.some((route) => route.mode === "vector")) {
+            return undefined;
+        }
+        const identity = {
+            provider: schema.provider,
+            name: schema.model,
+        };
+        const effectiveRuntime = resolveEmbeddingRuntimeOptions(embeddingModelReference(identity), this.options, workspaceRuntime, readGlobalConfig());
+        assertSearchEndpointMatchesWorkspace(info, workspaceRuntime, effectiveRuntime);
+        if (this.embeddingModel) {
+            return this.embeddingModel;
+        }
+        return this.recoverEmbeddingModel(schema, workspaceRuntime);
+    }
+    async embeddingModelForIndex(existing, operation, workspaceRuntime = {}, embeddingConcurrency) {
+        if (isWorkspaceIndexed(existing) &&
+            !this.embeddingModel &&
+            !this.options.embedding) {
+            const concurrency = resolveIndexEmbeddingConcurrency({
+                provider: existing.embedding.provider,
+                name: existing.embedding.model,
+            }, embeddingConcurrency ?? this.options.embeddingConcurrency);
+            return {
+                model: await this.recoverEmbeddingModel(existing.embedding, workspaceRuntime, concurrency),
+                concurrency,
+            };
+        }
+        const config = readGlobalConfig();
+        const reference = resolveEmbeddingReference({
+            explicit: this.options.embedding,
+            globalDefault: config.defaults?.embedding,
+            fallback: DEFAULT_LOCAL_EMBEDDING,
+        });
+        const referenceIdentity = reference
+            ? parseEmbeddingModelReference(reference)
+            : undefined;
+        const selectedWorkspaceRuntime = isWorkspaceIndexed(existing) &&
+            referenceIdentity &&
+            existing.embedding.provider !== referenceIdentity.provider
+            ? {}
+            : workspaceRuntime;
+        const identity = this.embeddingModel
+            ? {
+                provider: this.embeddingModel.info.provider,
+                name: this.embeddingModel.info.name,
+            }
+            : referenceIdentity;
+        const concurrency = identity
+            ? resolveIndexEmbeddingConcurrency(identity, embeddingConcurrency ?? this.options.embeddingConcurrency)
+            : undefined;
+        const model = this.embeddingModel ??
+            (reference
+                ? await this.embeddingModelFromReference(reference, config, selectedWorkspaceRuntime, concurrency)
+                : undefined) ??
+            this.requireEmbeddingModel(operation);
+        return { model, concurrency };
+    }
+    async recoverEmbeddingModel(schema, workspaceRuntime = {}, embeddingConcurrency) {
+        const config = readGlobalConfig();
+        const identity = {
+            provider: schema.provider,
+            name: schema.model,
+        };
+        const reference = embeddingModelReference(identity);
+        const options = providerOptions(this.options, identity, config, workspaceRuntime, embeddingConcurrency);
+        const key = `${reference}/${providerOptionsFingerprint(options)}`;
+        return this.cachedEmbeddingModel(key, () => createServiceEmbeddingModel(reference, options, this.options), localEmbeddingVariant(reference, options));
+    }
+    async embeddingModelFromReference(reference, config = readGlobalConfig(), workspaceRuntime = {}, embeddingConcurrency) {
+        const identity = parseEmbeddingModelReference(reference);
+        const options = providerOptions(this.options, identity, config, workspaceRuntime, embeddingConcurrency);
+        const key = `configured/${reference}/${providerOptionsFingerprint(options)}`;
+        return this.cachedEmbeddingModel(key, () => createServiceEmbeddingModel(reference, options, this.options), localEmbeddingVariant(reference, options));
+    }
+    cachedEmbeddingModel(key, create, variant) {
+        // Serialize cache selection, not inference. A caller arriving during an
+        // idle model's disposal must wait before it can load another GPU model.
+        const selected = this.modelSelectionPromise.then(async () => {
+            this.ensureOpen();
+            if (variant && this.activeEmbeddingModelOperations <= 1) {
+                for (const [cachedKey, cachedVariant] of this.localEmbeddingVariants) {
+                    if (cachedVariant.family === variant.family &&
+                        cachedVariant.concurrency !== variant.concurrency) {
+                        this.retireEmbeddingModel(cachedKey);
+                    }
+                }
+            }
+            if (this.activeEmbeddingModelOperations <= 1) {
+                // Only this operation remains, and its previous phase has finished.
+                // Other active operations may still hold retired models, so otherwise
+                // defer disposal until the final operation exits.
+                await this.disposeRetiredEmbeddingModels();
+            }
+            else {
+                await this.modelDisposalPromise;
+            }
+            this.ensureOpen();
+            const equivalentKey = variant
+                ? [...this.localEmbeddingVariants].find(([, cachedVariant]) => cachedVariant.family === variant.family &&
+                    cachedVariant.concurrency === variant.concurrency)?.[0]
+                : undefined;
+            const cachedKey = this.recoveredEmbeddingModels.has(key)
+                ? key
+                : (equivalentKey ?? key);
+            const cached = this.recoveredEmbeddingModels.get(cachedKey);
+            if (cached) {
+                this.recoveredEmbeddingModels.delete(cachedKey);
+                this.recoveredEmbeddingModels.set(cachedKey, cached);
+                return cached;
+            }
+            const model = create();
+            this.recoveredEmbeddingModels.set(key, model);
+            if (variant)
+                this.localEmbeddingVariants.set(key, variant);
+            this.trimRecoveredEmbeddingModels();
+            return model;
+        });
+        this.modelSelectionPromise = selected.then(() => undefined, () => undefined);
+        return selected;
+    }
+    retireEmbeddingModel(key) {
+        const model = this.recoveredEmbeddingModels.get(key);
+        this.recoveredEmbeddingModels.delete(key);
+        this.localEmbeddingVariants.delete(key);
+        if (model)
+            this.retiredEmbeddingModels.add(model);
+    }
+    trimRecoveredEmbeddingModels() {
+        while (this.recoveredEmbeddingModels.size > MAX_RECOVERED_EMBEDDING_MODELS) {
+            const oldestKey = this.recoveredEmbeddingModels.keys().next().value;
+            if (oldestKey === undefined) {
+                return;
+            }
+            this.retireEmbeddingModel(oldestKey);
+        }
+    }
+    retireIdleEmbeddingVariants() {
+        const retainedFamilies = new Set();
+        for (const key of [...this.recoveredEmbeddingModels.keys()].reverse()) {
+            const variant = this.localEmbeddingVariants.get(key);
+            if (!variant)
+                continue;
+            if (retainedFamilies.has(variant.family)) {
+                this.retireEmbeddingModel(key);
+            }
+            else {
+                retainedFamilies.add(variant.family);
+            }
+        }
+    }
+    async withEmbeddingModelOperation(operation) {
+        this.activeEmbeddingModelOperations += 1;
+        try {
+            return await operation();
+        }
+        finally {
+            this.activeEmbeddingModelOperations -= 1;
+            if (this.activeEmbeddingModelOperations === 0) {
+                this.retireIdleEmbeddingVariants();
+                await this.disposeRetiredEmbeddingModels();
+            }
+        }
+    }
+    disposeRetiredEmbeddingModels() {
+        const models = [...this.retiredEmbeddingModels];
+        this.retiredEmbeddingModels.clear();
+        const disposal = this.modelDisposalPromise.then(() => disposeEmbeddingModels(models));
+        // Report this batch's failures to its caller, but let later cleanup and
+        // model selection continue after every disposal in the batch settles.
+        this.modelDisposalPromise = disposal.then(() => undefined, () => undefined);
+        return disposal;
+    }
+    requireEmbeddingModel(operation) {
+        if (!this.embeddingModel) {
+            throw new EngineError("zvec-grep operation requires an embedding model", {
+                code: "ZVEC_GREP.ENGINE.SERVICE.EMBEDDING_MODEL_REQUIRED",
+                context: errorDetails([
+                    detail("operation", operation),
+                    detail("hint", `Pass "--embedding <model>", set ZVEC_GREP_EMBEDDING, or configure defaults.embedding in ${globalConfigPath()}. Existing indexes can run "zg --index" without --embedding to reuse the stored schema.`),
+                    detail("examples", "local/potion-code-16m-v2, qwen/text-embedding-v4"),
+                ]),
+            });
+        }
+        return this.embeddingModel;
+    }
+    ensureOpen() {
+        if (this.closed) {
+            throw new EngineError("zvec-grep service is already closed", {
+                code: "ZVEC_GREP.ENGINE.SERVICE.CLOSED",
+            });
+        }
+    }
+}
+async function disposeEmbeddingModels(models) {
+    const errors = [];
+    for (const model of models) {
+        try {
+            await model.dispose();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1) {
+        throw new AggregateError(errors, "Failed to dispose embedding models");
+    }
+}
+async function contextFromOpenWorkspaceIndex(input) {
+    const searches = [];
+    const groups = input.options.fuse
+        ? [
+            {
+                id: "Q1",
+                query: input.request.displayQuery,
+                role: input.request.groups.some((group) => group.role === "primary")
+                    ? "primary"
+                    : "supplemental",
+                routes: input.request.routes,
+            },
+        ]
+        : input.request.groups;
+    const limit = contextGroupLimit(input.options.limit, groups.length);
+    for (const group of groups) {
+        const search = await input.workspaceIndex.searchPlan({
+            routes: group.routes,
+            limit,
+            trace: input.options.trace,
+            preferSymbol: input.options.preferSymbol,
+            symbolTypes: input.options.symbolTypes,
+            includePaths: input.options.includePaths,
+            excludePaths: input.options.excludePaths,
+            globs: input.options.globs,
+            insensitiveGlobs: input.options.insensitiveGlobs,
+            fileTypes: input.options.fileTypes,
+            excludedFileTypes: input.options.excludedFileTypes,
+            modifiedAfter: input.options.modifiedAfter,
+            modifiedBefore: input.options.modifiedBefore,
+        });
+        input.timings.addEntries(search.timings);
+        searches.push(search);
+    }
+    const groupItems = searches.map((search, index) => searchPlanToContextItems(search, input.root, groups[index]));
+    const items = selectAndRankContextItems(groupItems.flat(), groups.filter((group) => group.role === "primary").map((group) => group.id));
+    return {
+        query: input.request.displayQuery,
+        root: input.root,
+        source: "index",
+        coverage: "ranked_sample",
+        workspaceIndex: {
+            id: input.workspaceIndex.info.id,
+            name: input.workspaceIndex.info.name,
+            path: input.workspaceIndex.info.path,
+        },
+        items,
+        groupResults: groups.map((group, index) => ({
+            id: group.id,
+            query: group.query,
+            role: group.role,
+            items: groupItems[index] ?? [],
+        })),
+        diagnostics: {
+            emptyReason: items.length === 0 ? "no_matches" : undefined,
+            index: {
+                hitsReturned: items.length,
+                queryGroups: groups.map((group) => ({
+                    id: group.id,
+                    query: group.query,
+                    role: group.role,
+                })),
+                routes: searches.flatMap((search) => search.plan.routes),
+            },
+        },
+    };
+}
+async function withHomeReadLock(home, operation, task) {
+    const lock = acquireHomeLock(home, "read", operation);
+    try {
+        return await task();
+    }
+    finally {
+        lock.release();
+    }
+}
+async function withHomeWriteLock(home, operation, task) {
+    const lock = acquireHomeLock(home, "write", operation);
+    try {
+        return await task();
+    }
+    finally {
+        lock.release();
+    }
+}
+async function workspaceIndexNeedsRefresh(location) {
+    const manifest = readWorkspaceManifest(location.home);
+    const status = manifest
+        ? await workspaceIndexStatus(manifest, location)
+        : null;
+    return indexStatusNeedsRefresh(status);
+}
+function acquireHomeLock(home, mode, operation) {
+    return acquireReadWriteLock(homeLockPath(home), mode, { operation });
+}
+function assertHomeUnlocked(home, operation) {
+    assertNoWriteLock(homeLockPath(home), operation);
+}
+function assertNearestWorkspaceHomeUnlocked(start, operation) {
+    let current = resolve(start);
+    while (true) {
+        assertHomeUnlocked(workspaceHome(current), operation);
+        const parent = dirname(current);
+        if (parent === current) {
+            return;
+        }
+        current = parent;
+    }
+}
+function homeLockPath(home) {
+    return join(home, "locks", "home");
+}
+function rgEmptyReason(diagnostics) {
+    return diagnostics.missingPaths &&
+        diagnostics.missingPaths.length > 0 &&
+        diagnostics.searchedPaths &&
+        diagnostics.searchedPaths.length === 0
+        ? "no_searchable_files"
+        : "no_matches";
+}
+function withContextTimings(result, timings) {
+    const entries = timings.entries();
+    if (entries.length === 0) {
+        return result;
+    }
+    return {
+        ...result,
+        diagnostics: {
+            ...result.diagnostics,
+            timings: entries,
+        },
+    };
+}
+function findNearestWorkspaceIndex(start) {
+    const location = findNearestWorkspace(start);
+    if (!location)
+        return null;
+    const info = readWorkspaceManifest(location.home);
+    return info ? { location, info } : null;
+}
+function workspaceInfoSuggestion(workspaceIndex) {
+    if (!workspaceIndex) {
+        return "zg --index or zg --rg";
+    }
+    if (workspaceIndex.indexPolicy === "disabled") {
+        return "zg --rg";
+    }
+    if (!isWorkspaceIndexed(workspaceIndex)) {
+        return "zg --index";
+    }
+    return undefined;
+}
+function workspaceIndexMissingError(root, policy) {
+    return new EngineError("No zvec-grep index found for this workspace", {
+        code: "ZVEC_GREP.ENGINE.SERVICE.WORKSPACE_INDEX_NOT_FOUND",
+        context: errorDetails([
+            detail("root", root),
+            detail("policy", policy),
+            detail("hint", policy === "undecided"
+                ? "Ask the user whether to build an index with zg --index, or use zg --rg for no-index search."
+                : "Run zg --index to build the enabled workspace index, or use zg --rg for no-index search."),
+            detail("agent_prompt", policy === "undecided"
+                ? "Ask the user whether this workspace should be indexed. If yes, run zg --index --embedding <model> with appropriate -g/--glob and -t/--type filters; otherwise use zg --rg for immediate no-index search."
+                : "This workspace is marked index-enabled but has no built index. Ask before running zg --index if an embedding model or cost is involved; otherwise use zg --rg for immediate no-index search."),
+        ]),
+    });
+}
+function workspaceIndexDisabledError(root) {
+    return new EngineError("The zvec-grep index is disabled for this workspace", {
+        code: "ZVEC_GREP.ENGINE.SERVICE.WORKSPACE_INDEX_DISABLED",
+        context: errorDetails([
+            detail("root", root),
+            detail("policy", "disabled"),
+            detail("hint", "Use zg --rg for no-index search. Run zg --index only if the user explicitly decides to index this workspace."),
+            detail("agent_action", "do_not_build_index"),
+        ]),
+    });
+}
+function resolveIndexRootPaths(existing, requested, fallbackRoot, options) {
+    let rootPaths = requested
+        ? inheritRequestedRootPathSettings(requested, existing?.rootPaths)
+        : (existing?.rootPaths ?? [fallbackRoot]);
+    if (options.resetPaths) {
+        rootPaths = rootPaths.map(resetRootPathFilters);
+    }
+    if (options.includePaths !== undefined ||
+        options.excludePaths !== undefined ||
+        options.globs !== undefined ||
+        options.insensitiveGlobs !== undefined ||
+        options.fileTypes !== undefined ||
+        options.excludedFileTypes !== undefined ||
+        options.hidden !== undefined ||
+        options.noIgnore !== undefined ||
+        options.ignoreFiles !== undefined ||
+        options.maxDepth !== undefined ||
+        options.maxFileSizeBytes !== undefined ||
+        options.follow !== undefined) {
+        rootPaths = rootPaths.map((rootPath) => applyRootPathOverrides(rootPath, options));
+    }
+    return rootPaths;
+}
+function inheritRequestedRootPathSettings(requested, existing) {
+    if (!existing?.length) {
+        return requested;
+    }
+    return requested.map((rootPath) => {
+        const absolutePath = normalizePath(typeof rootPath === "string" ? rootPath : rootPath.absolutePath);
+        const inherited = existing.find((candidate) => normalizePath(candidate.absolutePath) === absolutePath);
+        if (!inherited) {
+            return rootPath;
+        }
+        if (typeof rootPath === "string") {
+            return { ...inherited, absolutePath };
+        }
+        return {
+            ...inherited,
+            ...rootPath,
+            absolutePath,
+            include: rootPath.include ?? inherited.include,
+            exclude: rootPath.exclude ?? inherited.exclude,
+            globs: rootPath.globs ?? inherited.globs,
+            insensitiveGlobs: rootPath.insensitiveGlobs ?? inherited.insensitiveGlobs,
+            fileTypes: rootPath.fileTypes ?? inherited.fileTypes,
+            excludedFileTypes: rootPath.excludedFileTypes ?? inherited.excludedFileTypes,
+            hidden: rootPath.hidden ?? inherited.hidden,
+            noIgnore: rootPath.noIgnore ?? inherited.noIgnore,
+            ignoreFiles: rootPath.ignoreFiles ?? inherited.ignoreFiles,
+            maxDepth: rootPath.maxDepth ?? inherited.maxDepth,
+            maxFileSizeBytes: rootPath.maxFileSizeBytes ?? inherited.maxFileSizeBytes,
+            follow: rootPath.follow ?? inherited.follow,
+        };
+    });
+}
+function resetRootPathFilters(rootPath) {
+    if (typeof rootPath === "string") {
+        return rootPath;
+    }
+    return {
+        absolutePath: rootPath.absolutePath,
+        recursive: rootPath.recursive,
+    };
+}
+function applyRootPathOverrides(rootPath, options) {
+    const normalized = typeof rootPath === "string"
+        ? {
+            absolutePath: rootPath,
+            recursive: true,
+        }
+        : rootPath;
+    return {
+        ...normalized,
+        include: options.includePaths ?? normalized.include,
+        exclude: options.excludePaths ?? normalized.exclude,
+        globs: options.globs ?? normalized.globs,
+        insensitiveGlobs: options.insensitiveGlobs ?? normalized.insensitiveGlobs,
+        fileTypes: options.fileTypes ?? normalized.fileTypes,
+        excludedFileTypes: options.excludedFileTypes ?? normalized.excludedFileTypes,
+        hidden: options.hidden ?? normalized.hidden,
+        noIgnore: options.noIgnore ?? normalized.noIgnore,
+        ignoreFiles: options.ignoreFiles ?? normalized.ignoreFiles,
+        maxDepth: options.maxDepth ?? normalized.maxDepth,
+        maxFileSizeBytes: options.maxFileSizeBytes ?? normalized.maxFileSizeBytes,
+        follow: options.follow ?? normalized.follow,
+    };
+}
+function prepareWorkspaceManifest(location, existing, rootPaths, embeddingModel, embeddingRuntime) {
+    const now = Date.now();
+    return {
+        manifestVersion: CURRENT_MANIFEST_VERSION,
+        id: existing?.id ?? randomUUID(),
+        name: existing?.name ?? workspaceDisplayName(location.root),
+        path: location.home,
+        rootPaths: validateRootPaths(rootPaths),
+        indexPolicy: "enabled",
+        embedding: currentEmbeddingSchema(embeddingModel),
+        indexVersion: CURRENT_INDEX_VERSION,
+        createdTime: existing?.createdTime ?? now,
+        updatedTime: now,
+        embeddingRuntime,
+    };
+}
+function currentEmbeddingSchema(embeddingModel) {
+    return {
+        provider: embeddingModel.info.provider,
+        model: embeddingModel.info.name,
+        dimension: embeddingModel.info.dimension,
+        metric: embeddingModel.info.metric,
+    };
+}
+function workspaceDisplayName(root) {
+    return basename(normalizePath(root)) || "workspace";
+}
+async function workspaceIndexStatus(info, location) {
+    if (info.indexPolicy === "disabled" ||
+        !isWorkspaceIndexed(info) ||
+        !hasWorkspaceIndex(location)) {
+        return null;
+    }
+    const workspaceIndex = new WorkspaceIndex(info, { mode: "read" });
+    try {
+        return await workspaceIndex.status();
+    }
+    finally {
+        workspaceIndex.close();
+    }
+}
+function indexedEmbeddingSchema(info) {
+    if (isWorkspaceIndexed(info)) {
+        return info.embedding;
+    }
+    throw new EngineError("zvec-grep index has not been built", {
+        code: "ZVEC_GREP.ENGINE.SERVICE.INDEX_MISSING",
+        context: errorDetails([
+            workspaceIndexDetail(info.name),
+            detail("hint", "Run zg --index to build this index."),
+        ]),
+    });
+}
+/** Resolve index-stage batch concurrency; query model creation never reads it. */
+export function resolveIndexEmbeddingConcurrency(identity, requested) {
+    const backend = getEmbeddingModelCatalogEntry(embeddingModelReference(identity))?.backend;
+    return resolveIndexEmbeddingConcurrencyOverride({
+        embeddingConcurrency: requested,
+        legacyLlama: backend === "llama-cpp",
+    });
+}
+function providerOptions(options, identity, config = readGlobalConfig(), workspaceRuntime = {}, embeddingConcurrency) {
+    const reference = embeddingModelReference(identity);
+    const backend = getEmbeddingModelCatalogEntry(reference)?.backend;
+    const parallelism = backend === "llama-cpp" || backend === "transformers-js"
+        ? normalizeLocalEmbeddingConcurrency(embeddingConcurrency)
+        : undefined;
+    const runtime = resolveEmbeddingRuntimeOptions(reference, options, workspaceRuntime, config);
+    return {
+        apiKey: runtime.apiKey,
+        endpoint: runtime.endpoint,
+        modelCacheDir: options.modelCacheDir ??
+            config.defaults?.modelCacheDir ??
+            process.env.ZVEC_GREP_MODEL_CACHE ??
+            join(options.home ?? defaultHome(), "models"),
+        device: runtime.device,
+        ...(parallelism !== undefined ? { embeddingConcurrency: parallelism } : {}),
+    };
+}
+function localEmbeddingVariant(reference, options) {
+    const backend = getEmbeddingModelCatalogEntry(reference)?.backend;
+    if (backend !== "llama-cpp" && backend !== "transformers-js") {
+        return undefined;
+    }
+    return {
+        family: `${reference}/${providerOptionsFingerprint({
+            ...options,
+            embeddingConcurrency: undefined,
+        })}`,
+        concurrency: options.embeddingConcurrency ??
+            (backend === "transformers-js" ||
+                options.device === "cpu" ||
+                options.device === undefined
+                ? 1
+                : undefined),
+    };
+}
+function createServiceEmbeddingModel(reference, modelOptions, serviceOptions) {
+    const model = createEmbeddingModel(reference, modelOptions);
+    if (model.info.provider !== "qwen") {
+        return model;
+    }
+    const endpoint = model.info.endpoint;
+    if (endpoint === undefined) {
+        throw new EngineError("Remote embedding model did not provide an endpoint", {
+            code: "ZVEC_GREP.ENGINE.MODELS.REMOTE_ENDPOINT_NOT_IMPLEMENTED",
+            context: `model=${model.info.reference}`,
+        });
+    }
+    const authorize = remoteEmbeddingAuthorizationGuard({
+        store: new RemoteEmbeddingAuthorizationStore({
+            signingKeyPath: serviceOptions.authorizationSigningKeyPath,
+        }),
+    });
+    const authorizedModel = {
+        info: model.info,
+        async embed(contents, embedOptions) {
+            await authorize({
+                provider: model.info.provider,
+                model: model.info.name,
+                endpoint,
+                purpose: embedOptions?.purpose ?? EmbeddingPurpose.Document,
+                contentKinds: contents.map((content) => content.kind),
+                contentCount: contents.length,
+            });
+            return await model.embed(contents, embedOptions);
+        },
+        dispose: () => model.dispose(),
+    };
+    return authorizedModel;
+}
+function parseEmbeddingModelReference(reference) {
+    const separator = reference.indexOf("/");
+    if (separator <= 0 || separator === reference.length - 1) {
+        throw new EngineError("Embedding model reference is invalid", {
+            code: "ZVEC_GREP.ENGINE.MODELS.EMBEDDING_INVALID_REFERENCE",
+            context: `reference=${reference}`,
+        });
+    }
+    return {
+        provider: reference.slice(0, separator),
+        name: reference.slice(separator + 1),
+    };
+}
+function embeddingModelReference(identity) {
+    return `${identity.provider}/${identity.name}`;
+}
+function providerOptionsFingerprint(options) {
+    const publicOptionsFingerprint = createHash("sha256")
+        .update(JSON.stringify([
+        options.endpoint,
+        options.modelCacheDir,
+        options.device,
+        options.embeddingConcurrency,
+    ]))
+        .digest("hex");
+    return `${providerApiKeyIdentity(options.apiKey)}:${publicOptionsFingerprint}`;
+}
+function providerApiKeyIdentity(apiKey) {
+    return createHmac("sha256", PROVIDER_API_KEY_IDENTITY_SECRET)
+        .update(apiKey)
+        .digest("hex");
+}
+function effectiveEmbeddingRuntime(options, model, workspaceRuntime) {
+    const resolved = resolveEmbeddingRuntimeOptions(model.info.reference, options, workspaceRuntime, readGlobalConfig());
+    return {
+        apiKey: resolved.apiKey,
+        ...((model.info.endpoint ?? resolved.endpoint)
+            ? { endpoint: model.info.endpoint ?? resolved.endpoint }
+            : {}),
+        ...(model.info.provider === "local"
+            ? { device: resolved.device ?? "auto" }
+            : {}),
+    };
+}
+function runtimeForModelProvider(existing, model, workspaceRuntime) {
+    return isWorkspaceIndexed(existing) &&
+        existing.embedding.provider !== model.info.provider
+        ? {}
+        : workspaceRuntime;
+}
+function embeddingRuntimeAfterIndex(existing, existingRuntime, model, effectiveRuntime, explicit) {
+    const sameProvider = isWorkspaceIndexed(existing) &&
+        existing.embedding.provider === model.info.provider;
+    const apiKey = model.info.provider === "local"
+        ? undefined
+        : (explicit.apiKey ??
+            (sameProvider ? existingRuntime.apiKey : undefined));
+    return {
+        ...(apiKey !== undefined ? { apiKey } : {}),
+        ...(model.info.provider !== "local" &&
+            effectiveRuntime.endpoint !== undefined
+            ? { endpoint: effectiveRuntime.endpoint }
+            : {}),
+        ...(model.info.provider === "local"
+            ? { device: effectiveRuntime.device ?? "auto" }
+            : {}),
+    };
+}
+function assertWorkspaceEndpointMatchesCurrentRuntime(info, workspaceRuntime, effectiveRuntime, rebuildCommand) {
+    if (!isWorkspaceIndexed(info) ||
+        workspaceRuntime.endpoint === effectiveRuntime.endpoint) {
+        return;
+    }
+    throw new EngineError("Existing zvec-grep index uses a different embedding endpoint", {
+        code: "ZVEC_GREP.ENGINE.SERVICE.EMBEDDING_ENDPOINT_CHANGE_REQUIRES_REBUILD",
+        context: errorDetails([
+            workspaceIndexDetail(info.name),
+            detail("hint", `Run "${rebuildCommand}" to rebuild this index with the requested endpoint.`),
+        ]),
+    });
+}
+function assertSearchEndpointMatchesWorkspace(info, workspaceRuntime, effectiveRuntime) {
+    if (workspaceRuntime.endpoint === effectiveRuntime.endpoint) {
+        return;
+    }
+    throw new EngineError("Search cannot override the embedding endpoint of an existing index", {
+        code: "ZVEC_GREP.ENGINE.SERVICE.SEARCH_ENDPOINT_CHANGE_REQUIRES_REBUILD",
+        context: errorDetails([
+            workspaceIndexDetail(info.name),
+            detail("hint", 'Run "zg --index --endpoint <url> --rebuild" before searching with this endpoint.'),
+        ]),
+    });
+}
+function assertWorkspaceEmbeddingMatchesCurrentModel(info, model, rebuildCommand) {
+    if (!isWorkspaceIndexed(info)) {
+        return;
+    }
+    const expected = info.embedding;
+    const changed = expected.provider !== model.info.provider ||
+        expected.model !== model.info.name ||
+        expected.dimension !== model.info.dimension ||
+        expected.metric !== model.info.metric;
+    if (!changed) {
+        return;
+    }
+    throw new EngineError("Existing zvec-grep index uses a different embedding model", {
+        code: "ZVEC_GREP.ENGINE.SERVICE.EMBEDDING_SCHEMA_CHANGE_REQUIRES_REBUILD",
+        context: errorDetails([
+            workspaceIndexDetail(info.name),
+            detail("existing", `${expected.provider}/${expected.model}`),
+            detail("requested", model.info.reference),
+            detail("hint", `Run "${rebuildCommand}" to rebuild this index with the requested embedding model.`),
+        ]),
+    });
+}
+function contextGroupLimit(limit, groupCount) {
+    if (limit !== undefined) {
+        return limit;
+    }
+    const safeGroupCount = Math.max(1, groupCount);
+    if (safeGroupCount <= 3) {
+        return DEFAULT_CONTEXT_LIMIT;
+    }
+    return Math.max(1, Math.ceil(DEFAULT_CONTEXT_TOTAL_LIMIT / safeGroupCount));
+}
+function normalizeContextRequest(options) {
+    const primaryQueries = normalizePrimaryQueries(options.query, options.queries);
+    const extraRoutes = normalizeContextRoutes(options.routes ?? []);
+    const hasPatternFiles = options.rg === true && (options.rgOptions?.patternFiles?.length ?? 0) > 0;
+    if (primaryQueries.length === 0 &&
+        extraRoutes.length === 0 &&
+        !hasPatternFiles) {
+        throw new EngineError("zvec-grep context requires a non-empty query or route", {
+            code: "ZVEC_GREP.ENGINE.SERVICE.EMPTY_QUERY",
+        });
+    }
+    const groups = contextGroups(primaryQueries, extraRoutes);
+    const routes = groups.flatMap((group) => group.routes);
+    const rgPatterns = [
+        ...primaryQueries,
+        ...extraRoutes.map((route) => route.query),
+    ];
+    const displayQuery = primaryQueries.length > 0
+        ? primaryQueries.join(" | ")
+        : extraRoutes.length > 0
+            ? extraRoutes.map((route) => route.query).join(" | ")
+            : options
+                .rgOptions.patternFiles.map((path) => `@${path}`)
+                .join(" | ");
+    return {
+        displayQuery,
+        rgPatterns,
+        routes,
+        groups,
+    };
+}
+function normalizePrimaryQueries(query, queries) {
+    return [query, ...(queries ?? [])].flatMap((value) => {
+        const normalized = normalizeOptionalQuery(value);
+        return normalized ? [normalized] : [];
+    });
+}
+function normalizeOptionalQuery(query) {
+    const normalized = query?.trim() ?? "";
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeContextRoutes(routes) {
+    return routes.map((route, index) => {
+        if (route.mode !== "fts" && route.mode !== "vector") {
+            throw new EngineError("zvec-grep context route has an unsupported mode", {
+                code: "ZVEC_GREP.ENGINE.SERVICE.INVALID_ROUTE_MODE",
+                context: `routeIndex=${index} mode=${String(route.mode)}`,
+            });
+        }
+        const query = route.query.trim();
+        if (query.length === 0) {
+            throw new EngineError("zvec-grep context route requires a non-empty query", {
+                code: "ZVEC_GREP.ENGINE.SERVICE.EMPTY_ROUTE_QUERY",
+                context: `routeIndex=${index} mode=${route.mode}`,
+            });
+        }
+        return {
+            mode: route.mode,
+            query,
+        };
+    });
+}
+function contextGroups(primaryQueries, extraRoutes) {
+    return [
+        ...primaryQueries.map((query, index) => ({
+            id: `Q${index + 1}`,
+            query,
+            role: "primary",
+            routes: [
+                { mode: "fts", query },
+                { mode: "vector", query },
+            ],
+        })),
+        ...extraRoutes.map((route, index) => ({
+            id: `Q${primaryQueries.length + index + 1}`,
+            query: route.query,
+            role: "supplemental",
+            routes: [route],
+        })),
+    ];
+}
+function searchPlanToContextItems(result, root, group) {
+    return result.hits.map((hit) => {
+        const target = contextItemTarget(hit);
+        return {
+            kind: "indexed_entity",
+            rank: hit.rank,
+            file: {
+                absolutePath: hit.file.absolutePath,
+                relativePath: hit.file.relativePath || relative(root, hit.file.absolutePath) || ".",
+                rootPath: hit.file.rootPath,
+            },
+            range: hit.entity.range,
+            excerptRange: target.excerptRange,
+            content: contentToText(target.content),
+            contentRole: target.contentRole,
+            outline: target.outline,
+            status: fileFreshnessStatus(hit.file),
+            score: hit.score,
+            matchedBy: hit.matchedBy,
+            metadata: hit.entity.metadata,
+            entityId: hit.entity.id,
+            trace: hit.trace,
+            queryGroups: [
+                {
+                    id: group.id,
+                    query: group.query,
+                    role: group.role,
+                    rank: hit.rank,
+                    matchedBy: hit.matchedBy,
+                },
+            ],
+        };
+    });
+}
+const DEFAULT_CONTEXT_PRIORITY_LIMIT = 6;
+const CONTEXT_GROUP_RRF_K = 60;
+function selectAndRankContextItems(items, coverageGroupIds) {
+    const deduped = new Map();
+    for (const item of items) {
+        const key = contextItemDedupeKey(item);
+        const existing = deduped.get(key);
+        if (existing) {
+            existing.queryGroups = mergeContextQueryGroupMatches(existing.queryGroups ?? [], item.queryGroups ?? []);
+            existing.matchedBy = mergedContextMatchedBy(existing.queryGroups);
+            continue;
+        }
+        deduped.set(key, { ...item });
+    }
+    const candidates = [...deduped.values()];
+    const globallyRanked = [...candidates].sort(compareContextGlobalRank);
+    const selected = new Set();
+    const prioritized = [];
+    for (const groupId of coverageGroupIds) {
+        if (prioritized.length >= DEFAULT_CONTEXT_PRIORITY_LIMIT) {
+            break;
+        }
+        const candidate = candidates
+            .filter((item) => !selected.has(contextItemDedupeKey(item)))
+            .filter((item) => contextQueryGroupMatch(item, groupId) !== undefined)
+            .sort((left, right) => compareContextGroupRank(left, right, groupId))[0];
+        if (!candidate) {
+            continue;
+        }
+        selected.add(contextItemDedupeKey(candidate));
+        prioritized.push({
+            ...candidate,
+            selectionReason: "coverage",
+            coverageGroup: groupId,
+        });
+    }
+    for (const candidate of globallyRanked) {
+        if (prioritized.length >= DEFAULT_CONTEXT_PRIORITY_LIMIT) {
+            break;
+        }
+        const key = contextItemDedupeKey(candidate);
+        if (selected.has(key)) {
+            continue;
+        }
+        selected.add(key);
+        prioritized.push({
+            ...candidate,
+            selectionReason: "global_fill",
+            coverageGroup: undefined,
+        });
+    }
+    const unprioritized = globallyRanked.filter((item) => !selected.has(contextItemDedupeKey(item)));
+    return [...prioritized, ...unprioritized].map((item, index) => ({
+        ...item,
+        rank: index + 1,
+    }));
+}
+function dedupeAndRerankContextItems(items) {
+    const seen = new Set();
+    const deduped = [];
+    for (const item of items) {
+        const key = contextItemDedupeKey(item);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push({ ...item, rank: deduped.length + 1 });
+    }
+    return deduped;
+}
+function mergeContextQueryGroupMatches(left, right) {
+    const matches = new Map(left.map((match) => [match.id, match]));
+    for (const match of right) {
+        const existing = matches.get(match.id);
+        if (!existing || match.rank < existing.rank) {
+            matches.set(match.id, match);
+        }
+    }
+    return [...matches.values()].sort((a, b) => contextGroupNumber(a.id) - contextGroupNumber(b.id));
+}
+function mergedContextMatchedBy(matches) {
+    const hasFts = matches.some((match) => match.matchedBy === "fts" || match.matchedBy === "fts+vector");
+    const hasVector = matches.some((match) => match.matchedBy === "vector" || match.matchedBy === "fts+vector");
+    return hasFts && hasVector ? "fts+vector" : hasFts ? "fts" : "vector";
+}
+function compareContextGlobalRank(left, right) {
+    return (contextGlobalRrfScore(right) - contextGlobalRrfScore(left) ||
+        contextBestGroupRank(left) - contextBestGroupRank(right) ||
+        contextFirstGroupNumber(left) - contextFirstGroupNumber(right) ||
+        contextItemDedupeKey(left).localeCompare(contextItemDedupeKey(right)));
+}
+function contextGlobalRrfScore(item) {
+    return (item.queryGroups ?? []).reduce((score, match) => score + 1 / (CONTEXT_GROUP_RRF_K + match.rank), 0);
+}
+function compareContextGroupRank(left, right, groupId) {
+    return (contextQueryGroupMatch(left, groupId).rank -
+        contextQueryGroupMatch(right, groupId).rank ||
+        compareContextGlobalRank(left, right));
+}
+function contextQueryGroupMatch(item, groupId) {
+    return item.queryGroups?.find((match) => match.id === groupId);
+}
+function contextBestGroupRank(item) {
+    return Math.min(...(item.queryGroups ?? []).map((match) => match.rank));
+}
+function contextFirstGroupNumber(item) {
+    return Math.min(...(item.queryGroups ?? []).map((match) => contextGroupNumber(match.id)));
+}
+function contextGroupNumber(id) {
+    const value = Number.parseInt(id.slice(1), 10);
+    return Number.isFinite(value) ? value : Number.MAX_SAFE_INTEGER;
+}
+function contextItemDedupeKey(item) {
+    if (item.entityId) {
+        return `entity:${item.entityId}`;
+    }
+    return ["range", item.file.absolutePath, JSON.stringify(item.range)].join(":");
+}
+function contextItemTarget(hit) {
+    const evidence = hit.evidence.find((item) => !item.isEntity);
+    const hasSeparateEvidence = evidence && !sameDisplayedContent(hit.entity, evidence);
+    const content = hasSeparateEvidence ? evidence.content : hit.entity.content;
+    const contentRole = hasSeparateEvidence || entityContentLooksLikeSource(hit.entity)
+        ? "source"
+        : "outline";
+    const excerptRange = hasSeparateEvidence ? evidence.range : undefined;
+    const outline = contentRole === "source" ? contextItemOutline(hit, evidence) : undefined;
+    return {
+        content,
+        contentRole,
+        excerptRange,
+        outline,
+    };
+}
+function entityContentLooksLikeSource(entity) {
+    if (entity.content.kind !== "text" || entity.range.kind !== "text") {
+        return true;
+    }
+    const expectedLines = entity.range.endLine - entity.range.startLine + 1;
+    const actualLines = entity.content.text.split(/\r?\n/).length;
+    return actualLines >= expectedLines;
+}
+function contextItemOutline(hit, evidence) {
+    if (hit.entity.content.kind !== "text") {
+        return undefined;
+    }
+    const outline = hit.entity.content.text.trim();
+    if (outline.length === 0) {
+        return undefined;
+    }
+    if (!evidence) {
+        return undefined;
+    }
+    if (evidence && sameDisplayedContent(hit.entity, evidence)) {
+        return undefined;
+    }
+    if (!isUsefulOutline(hit.entity.metadata, outline)) {
+        return undefined;
+    }
+    if (evidence?.content.kind === "text" &&
+        evidence.content.text.trim() === outline) {
+        return undefined;
+    }
+    return outline;
+}
+function isUsefulOutline(metadata, outline) {
+    if (!metadata || metadata.kind !== "code") {
+        return false;
+    }
+    return (metadata.symbolType === "class" ||
+        metadata.symbolType === "interface" ||
+        metadata.symbolType === "module" ||
+        outline.includes("\ncalls:"));
+}
+function sameDisplayedContent(entity, evidence) {
+    return (JSON.stringify(entity.range) === JSON.stringify(evidence.range) &&
+        contentEquals(entity.content, evidence.content));
+}
+function contentEquals(left, right) {
+    if (left.kind !== right.kind) {
+        return false;
+    }
+    if (left.kind === "image") {
+        return (right.kind === "image" &&
+            left.format === right.format &&
+            left.data.byteLength === right.data.byteLength);
+    }
+    return right.kind === "text" && left.text === right.text;
+}
+function fileFreshnessStatus(file) {
+    if (!file.indexStatus?.indexedTime) {
+        return "possibly_stale";
+    }
+    try {
+        const info = statSync(file.absolutePath, { throwIfNoEntry: false });
+        if (!info || !info.isFile()) {
+            return "possibly_stale";
+        }
+        if (file.indexStatus.indexedTime >= info.mtimeMs) {
+            return "fresh";
+        }
+        if (file.contentHash &&
+            sha256File(file.absolutePath) === file.contentHash) {
+            return "fresh";
+        }
+    }
+    catch {
+        return "possibly_stale";
+    }
+    return "possibly_stale";
+}
+function sha256File(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function contentToText(content) {
+    if (content.kind === "text") {
+        return content.text;
+    }
+    return `[image:${content.format} bytes=${content.data.byteLength}]`;
+}
+//# sourceMappingURL=zvec-grep.js.map