@zvec/zvec-grep 0.1.4 → 0.1.6

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

@@ -1,439 +1,406 @@
-import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { dirname, join, relative, resolve } from "node:path";
-import { Collection, CollectionRegistry, isCollectionIndexed, } from "../collection/index.js";
-import { collectionDetail, detail, EngineError, errorDetails, } from "../errors/index.js";
-import { createEmbeddingModel, createEmbeddingModelFromReference, } from "../models/index.js";
-import { ANONYMOUS_COLLECTION_NAME, anonymousCollectionPath, anonymousHome, anonymousIndexLocation, resolveZvecGrepRoot, } from "./root.js";
-import { runLexicalFallback, runRgSearch } from "./lexical.js";
-import { defaultHome } from "../utils/path.js";
-import { acquireReadWriteLock, assertNoWriteLock } from "../utils/lock.js";
+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, resolveEmbeddingReference, } 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, resetWorkspaceIndexStorage, 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/embeddinggemma-300m";
+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, embeddingModel, true, location.filesPath);
+    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);
+}
+export function embeddingModelPoolKeyForIdentity(identity, options = {}, workspaceRuntime = {}) {
+    const reference = embeddingModelReference(identity);
+    const fingerprint = providerOptionsFingerprint(providerOptions(options, identity, readGlobalConfig(), workspaceRuntime));
+    return [reference, fingerprint].join("/");
+}
 class ZvecGrepService {
     options;
     root;
-    collections;
     embeddingModel;
-    embeddingModelExplicit;
     recoveredEmbeddingModels = new Map();
+    retiredEmbeddingModels = new Set();
+    activeEmbeddingModelOperations = 0;
     closed = false;
     constructor(options) {
         this.options = options;
         this.root = resolveZvecGrepRoot(options.root);
-        this.embeddingModelExplicit = hasExplicitEmbeddingModel(options);
-        this.embeddingModel = resolveEmbeddingModel(options, this.root);
-        this.collections = {
-            list: () => this.listCollections(),
-            info: (name) => this.collectionInfo(name),
-            status: (name) => this.collectionStatus(name),
-            index: (name, paths, indexOptions) => this.indexCollection(name, paths, indexOptions),
-            remove: (name) => this.removeCollection(name),
-        };
+        this.embeddingModel = options.embeddingModel;
     }
     async index(options = {}) {
         this.ensureOpen();
         const root = resolveZvecGrepRoot(options.root ?? this.root);
-        const location = anonymousIndexLocation(root);
-        return await withHomeWriteLock(location.home, options.rebuild ? "index.rebuild" : "index", async () => {
-            const existing = readCollectionInfo(location.home, ANONYMOUS_COLLECTION_NAME);
-            const embeddingModel = this.embeddingModelForIndex(existing, location.home, "index");
-            const registry = new CollectionRegistry(location.home, embeddingModel);
-            try {
+        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 embeddingModel = this.embeddingModelForIndex(existing, "index", existingRuntime);
+                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) {
-                    registry.remove(ANONYMOUS_COLLECTION_NAME);
+                if (options.rebuild || !isWorkspaceIndexed(existing)) {
+                    resetWorkspaceIndexStorage(location);
                 }
-                const existingAfterRebuild = registry.get(ANONYMOUS_COLLECTION_NAME);
-                if (isCollectionIndexed(existingAfterRebuild)) {
-                    assertCollectionEmbeddingMatchesCurrentModel(existingAfterRebuild, embeddingModel, "zg --index --rebuild");
+                const existingAfterRebuild = options.rebuild ? null : existing;
+                if (isWorkspaceIndexed(existingAfterRebuild)) {
+                    assertWorkspaceEmbeddingMatchesCurrentModel(existingAfterRebuild, embeddingModel, "zg index --rebuild");
                 }
-                registry.prepareIndex(ANONYMOUS_COLLECTION_NAME, rootPaths, anonymousCollectionPath(root));
-                return await registry.open(ANONYMOUS_COLLECTION_NAME).index({
-                    rebuild: false,
-                    embeddingConcurrency: options.embeddingConcurrency,
-                    onProgress: options.onProgress,
-                });
-            }
-            finally {
-                registry.close();
+                const manifest = prepareWorkspaceManifest(location, existingAfterRebuild, rootPaths, embeddingModel, existingRuntime);
+                const workspaceIndex = new WorkspaceIndex(manifest, embeddingModel, false, location.filesPath);
+                writeWorkspaceManifest(location.home, manifest);
+                try {
+                    const releaseWriterContext = options.onWriterContext?.((contextOptions) => this.contextFromWriterWorkspaceIndex(root, workspaceIndex, contextOptions));
+                    try {
+                        const result = await workspaceIndex.index({
+                            rebuild: false,
+                            embeddingConcurrency: options.embeddingConcurrency,
+                            onProgress: options.onProgress,
+                            changedPaths: options.changedPaths,
+                            signal: options.signal,
+                        });
+                        writeWorkspaceManifest(location.home, {
+                            ...manifest,
+                            embeddingRuntime: embeddingRuntimeAfterSuccessfulIndex(existing, existingRuntime, embeddingModel, effectiveRuntime, this.options),
+                            updatedTime: Date.now(),
+                        });
+                        return result;
+                    }
+                    catch (error) {
+                        writeWorkspaceManifest(location.home, {
+                            ...manifest,
+                            embeddingRuntime: existingRuntime,
+                            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 () => {
+                resetWorkspaceIndexStorage(location);
+                return true;
+            });
+        }
+        finally {
+            daemonWritePermit?.release();
+        }
     }
     async disableIndex(options = {}) {
         this.ensureOpen();
         const root = resolveZvecGrepRoot(options.root ?? this.root);
-        const location = anonymousIndexLocation(root);
-        await withHomeWriteLock(location.home, "index.disable", async () => {
-            const registry = new CollectionRegistry(location.home, undefined);
-            try {
-                registry.disableIndex(ANONYMOUS_COLLECTION_NAME, [root], location.collectionPath);
-            }
-            finally {
-                registry.close();
-            }
-        });
-        return this.info({ 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();
-        const timings = new TimingCollector();
-        const result = await timings.time("total", () => this.contextWithTimings(options, timings));
-        return withContextTimings(result, timings);
+        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);
-        if (options.collection) {
-            return this.contextFromNamedCollection(request, options, timings);
-        }
         const startRoot = resolveZvecGrepRoot(options.root ?? this.root);
         if (options.rg) {
             return this.contextFromRg(startRoot, request, options, timings);
         }
-        assertNearestAnonymousHomeUnlocked(startRoot, "context");
-        const nearest = findNearestAnonymousCollection(startRoot);
+        assertNearestWorkspaceHomeUnlocked(startRoot, "context");
+        const nearest = findNearestWorkspaceIndex(startRoot);
         if (nearest) {
             const { location, info } = nearest;
             if (info.indexPolicy === "disabled") {
-                throw anonymousIndexDisabledError(location.root);
+                throw workspaceIndexDisabledError(location.root);
             }
-            if (!isCollectionIndexed(info)) {
-                throw anonymousIndexMissingError(location.root, info.indexPolicy ?? "enabled");
+            if (!isWorkspaceIndexed(info) || !hasWorkspaceIndex(location)) {
+                throw workspaceIndexMissingError(location.root, info.indexPolicy ?? "enabled");
             }
             if (options.autoUpdate !== false) {
-                await this.refreshAnonymousIndexForContext(location, options, timings);
+                await this.refreshWorkspaceIndexForContext(location, options, timings);
             }
-            return await withHomeReadLock(location.home, "context", () => this.contextFromAnonymousIndex(location, request, options, timings));
+            return await withHomeReadLock(location.home, "context", () => this.contextFromWorkspaceIndex(location, request, options, timings));
         }
-        throw anonymousIndexMissingError(startRoot, "undecided");
+        throw workspaceIndexMissingError(startRoot, "undecided");
     }
     async info(options = {}) {
         this.ensureOpen();
         const startRoot = resolveZvecGrepRoot(options.root ?? this.root);
-        assertNearestAnonymousHomeUnlocked(startRoot, "info");
-        const nearest = findNearestAnonymousCollection(startRoot);
+        assertNearestWorkspaceHomeUnlocked(startRoot, "info");
+        const nearest = findNearestWorkspaceIndex(startRoot);
         if (!nearest) {
-            const location = anonymousIndexLocation(startRoot);
+            const location = workspaceIndexLocation(startRoot);
             return {
                 root: startRoot,
                 indexed: false,
                 indexPolicy: "undecided",
                 home: location.home,
-                indexPath: location.collectionPath,
+                indexPath: location.indexPath,
                 source: "unindexed",
-                suggestion: "zg --index or zg --rg",
+                suggestion: "zg index or zg query --rg",
             };
         }
         return await withHomeReadLock(nearest.location.home, "info", async () => {
-            const registry = new CollectionRegistry(nearest.location.home, undefined, true);
-            try {
-                const collection = registry.get(ANONYMOUS_COLLECTION_NAME);
-                const indexed = collection !== null
-                    && collection.indexPolicy !== "disabled"
-                    && isCollectionIndexed(collection);
-                return {
-                    root: nearest.location.root,
-                    indexed,
-                    indexPolicy: collection?.indexPolicy ?? "undecided",
-                    home: nearest.location.home,
-                    indexPath: nearest.location.collectionPath,
-                    source: indexed ? "index" : "unindexed",
-                    collection: collection ?? undefined,
-                    status: indexed ? await registry.status(ANONYMOUS_COLLECTION_NAME) : null,
-                    suggestion: anonymousInfoSuggestion(collection),
-                };
-            }
-            finally {
-                registry.close();
-            }
+            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() {
         const models = new Set([
-            ...(this.embeddingModel ? [this.embeddingModel] : []),
+            ...(this.embeddingModel &&
+                this.options.embeddingModelOwnership !== "borrowed"
+                ? [this.embeddingModel]
+                : []),
             ...this.recoveredEmbeddingModels.values(),
+            ...this.retiredEmbeddingModels,
         ]);
         this.recoveredEmbeddingModels.clear();
+        this.retiredEmbeddingModels.clear();
         for (const model of models) {
             await model.dispose();
         }
         this.closed = true;
     }
-    async listCollections() {
-        this.ensureOpen();
-        return await withHomeReadLock(serviceHome(this.options), "collections.list", async () => {
-            const registry = this.createRegistry(true);
-            try {
-                return registry.list();
-            }
-            finally {
-                registry.close();
-            }
-        });
-    }
-    async collectionInfo(name) {
-        this.ensureOpen();
-        return await withHomeReadLock(serviceHome(this.options), "collections.info", async () => {
-            const registry = this.createRegistry(true);
-            try {
-                return registry.get(name);
-            }
-            finally {
-                registry.close();
-            }
-        });
-    }
-    async collectionStatus(name) {
-        this.ensureOpen();
-        return await withHomeReadLock(serviceHome(this.options), "collections.status", async () => {
-            const registry = this.createRegistry(true);
-            try {
-                return await registry.status(name);
-            }
-            finally {
-                registry.close();
-            }
-        });
-    }
-    async indexCollection(name, paths, options = {}) {
-        this.ensureOpen();
-        const home = serviceHome(this.options);
-        return await withHomeWriteLock(home, options.rebuild ? "collections.index.rebuild" : "collections.index", async () => {
-            const existing = readCollectionInfo(home, name);
-            const embeddingModel = this.embeddingModelForIndex(existing, home, "collections.index");
-            const registry = this.createRegistry(false, embeddingModel);
-            try {
-                const requestedRootPaths = paths === undefined
-                    ? undefined
-                    : Array.isArray(paths)
-                        ? paths
-                        : [paths];
-                const rootPaths = resolveIndexRootPaths(existing, requestedRootPaths, this.root, {
-                    resetPaths: options.resetPaths === true,
-                    includePaths: options.includePaths,
-                    excludePaths: options.excludePaths,
-                });
-                if (options.rebuild) {
-                    registry.remove(name);
-                }
-                const existingAfterRebuild = registry.get(name);
-                if (isCollectionIndexed(existingAfterRebuild)) {
-                    assertCollectionEmbeddingMatchesCurrentModel(existingAfterRebuild, embeddingModel, "zg --collections index <name> --rebuild");
-                }
-                registry.prepareIndex(name, rootPaths);
-                return await registry.open(name).index({
-                    embeddingConcurrency: options.embeddingConcurrency,
-                    onProgress: options.onProgress,
-                });
-            }
-            finally {
-                registry.close();
-            }
-        });
-    }
-    async removeCollection(name) {
-        this.ensureOpen();
-        return await withHomeWriteLock(serviceHome(this.options), "collections.remove", async () => {
-            const registry = this.createRegistry(false);
-            try {
-                return registry.remove(name);
-            }
-            finally {
-                registry.close();
-            }
-        });
-    }
-    async contextFromAnonymousIndex(location, request, options, timings) {
-        const registry = new CollectionRegistry(location.home, undefined, true);
+    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 = this.openWorkspaceIndexForSearch(info, request, location, info.embeddingRuntime);
         try {
-            const info = registry.get(ANONYMOUS_COLLECTION_NAME);
-            if (!info) {
-                throw new EngineError("Collection not found", {
-                    code: "ZVEC_GREP.ENGINE.COLLECTION.NOT_FOUND",
-                });
-            }
-            const collection = this.openCollectionForSearch(info, request, location.home);
-            try {
-                return await this.contextFromCollection({
-                    root: location.root,
-                    request,
-                    collection,
-                    anonymous: true,
-                    options,
-                    timings,
-                });
-            }
-            finally {
-                collection.close();
-            }
+            return await contextFromOpenWorkspaceIndex({
+                root: location.root,
+                request,
+                workspaceIndex,
+                options,
+                timings,
+            });
         }
         finally {
-            registry.close();
+            workspaceIndex.close();
         }
     }
-    async refreshAnonymousIndexForContext(location, options, timings) {
-        const needsRefresh = await timings.time("status_scan", () => withHomeReadLock(location.home, "context.status", async () => {
-            const registry = new CollectionRegistry(location.home, undefined, true);
-            try {
-                const status = await registry.status(ANONYMOUS_COLLECTION_NAME);
-                return status ? collectionIndexStatusNeedsRefresh(status) : false;
-            }
-            finally {
-                registry.close();
-            }
-        }));
-        if (!needsRefresh) {
-            return;
-        }
-        await timings.time("auto_update", () => withHomeWriteLock(location.home, "context.refresh", async () => {
-            const existing = readCollectionInfo(location.home, ANONYMOUS_COLLECTION_NAME);
-            if (!existing) {
-                return;
-            }
-            const stillNeedsRefresh = await timings.time("refresh_status_scan", () => collectionNeedsRefresh(location.home, ANONYMOUS_COLLECTION_NAME));
-            if (!stillNeedsRefresh) {
+    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;
             }
-            const embeddingModel = this.embeddingModelForIndex(existing, location.home, "context.refresh");
-            assertCollectionEmbeddingMatchesCurrentModel(existing, embeddingModel, "zg --index --rebuild");
-            const registry = new CollectionRegistry(location.home, embeddingModel);
-            try {
-                const result = await registry.open(ANONYMOUS_COLLECTION_NAME).index({
-                    embeddingConcurrency: options.embeddingConcurrency,
-                    onProgress: options.onAutoUpdateProgress,
-                });
-                timings.addEntries(result.timings, "auto_update_");
-            }
-            finally {
-                registry.close();
-            }
-        }));
-    }
-    async contextFromNamedCollection(request, options, timings) {
-        const collectionName = options.collection;
-        return await withHomeReadLock(serviceHome(this.options), "collection.context", async () => {
-            const registry = this.createRegistry(true, undefined);
-            try {
-                const info = registry.get(collectionName);
-                if (!info) {
-                    throw new EngineError("Collection not found", {
-                        code: "ZVEC_GREP.ENGINE.COLLECTION.NOT_FOUND",
-                        context: errorDetails([collectionDetail(collectionName)]),
-                    });
+            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 collection = this.openCollectionForSearch(info, request, registry.home);
-                const root = collection.info.rootPaths[0]?.absolutePath ?? resolveZvecGrepRoot(options.root ?? this.root);
+                const workspaceRuntime = existing.embeddingRuntime;
+                const embeddingModel = this.embeddingModelForIndex(existing, "context.refresh", workspaceRuntime);
+                assertWorkspaceEndpointMatchesCurrentRuntime(existing, workspaceRuntime, effectiveEmbeddingRuntime(this.options, embeddingModel, workspaceRuntime), "zg index --endpoint <url> --rebuild");
+                assertWorkspaceEmbeddingMatchesCurrentModel(existing, embeddingModel, "zg index --rebuild");
+                const workspaceIndex = new WorkspaceIndex(existing, embeddingModel, false, location.filesPath);
                 try {
-                    return await this.contextFromCollection({
-                        root,
-                        request,
-                        collection,
-                        anonymous: false,
-                        options: {
-                            ...options,
-                            fallback: "disabled",
-                        },
-                        timings,
+                    const result = await workspaceIndex.index({
+                        embeddingConcurrency: options.embeddingConcurrency,
+                        onProgress: options.onAutoUpdateProgress,
                     });
+                    timings.addEntries(result.timings, "auto_update_");
                 }
                 finally {
-                    collection.close();
+                    workspaceIndex.close();
                 }
-            }
-            finally {
-                registry.close();
-            }
-        });
-    }
-    async contextFromCollection(input) {
-        const searches = [];
-        const limit = contextGroupLimit(input.options.limit, input.request.groups.length);
-        for (const group of input.request.groups) {
-            const search = await input.collection.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,
-                modifiedAfter: input.options.modifiedAfter,
-                modifiedBefore: input.options.modifiedBefore,
-            });
-            input.timings.addEntries(search.timings);
-            searches.push(search);
+            }));
+        }
+        finally {
+            daemonWritePermit?.release();
         }
-        const items = dedupeAndRerankContextItems(searches.flatMap((search) => searchPlanToContextItems(search, input.root)));
-        return {
-            query: input.request.displayQuery,
-            root: input.root,
-            source: "index",
-            coverage: "ranked_sample",
-            collection: {
-                id: input.collection.info.id,
-                name: input.collection.info.name,
-                path: input.collection.info.path,
-                anonymous: input.anonymous,
-            },
-            items,
-            diagnostics: {
-                emptyReason: items.length === 0 ? "no_matches" : undefined,
-                index: {
-                    hitsReturned: items.length,
-                    routes: searches.flatMap((search) => search.plan.routes),
-                },
-            },
-        };
     }
-    async contextFromLexicalFallback(root, request, options, timings) {
-        const fallbackResults = [];
-        const limit = contextGroupLimit(options.limit, request.groups.length);
-        for (const query of request.fallbackQueries) {
-            fallbackResults.push(await timings.time("fallback_search", () => runLexicalFallback({
+    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,
-                query,
-                limit,
-                includePaths: options.includePaths,
-                excludePaths: options.excludePaths,
-                modifiedAfter: options.modifiedAfter,
-                modifiedBefore: options.modifiedBefore,
-                rgOptions: options.rgOptions,
-            })));
-        }
-        const items = dedupeAndRerankContextItems(fallbackResults.flatMap((fallback) => fallback.items));
-        const diagnostics = mergeFallbackDiagnostics(fallbackResults);
-        return {
-            query: request.displayQuery,
-            root,
-            source: "lexical_fallback",
-            coverage: diagnostics.truncated ? "lexical_truncated" : "lexical_exhaustive",
-            items,
-            diagnostics: {
-                emptyReason: items.length === 0 ? "no_matches" : undefined,
-                fallback: diagnostics,
-            },
-        };
+                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.fallbackQueries,
+                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,
@@ -442,72 +409,142 @@ class ZvecGrepService {
         catch (cause) {
             throw new EngineError("Search failed", {
                 code: "ZVEC_GREP.ENGINE.SEARCH.FAILED",
-                context: errorDetails([
-                    detail("source", "rg"),
-                    detail("root", root),
-                ]),
+                context: errorDetails([detail("source", "rg"), detail("root", root)]),
                 cause,
             });
         }
         const structuralEnrichment = await timings.time("structure_enrichment", () => enrichLexicalItemsWithStructure(root, rgResult.items));
         const items = dedupeAndRerankContextItems(structuralEnrichment.items);
-        const emptyReason = items.length === 0
-            ? rgEmptyReason(rgResult.diagnostics)
-            : undefined;
+        const emptyReason = items.length === 0 ? rgEmptyReason(rgResult.diagnostics) : undefined;
         return {
             query: request.displayQuery,
             root,
             source: "rg",
-            coverage: rgResult.diagnostics.truncated ? "lexical_truncated" : "lexical_exhaustive",
+            coverage: rgResult.diagnostics.truncated
+                ? "rg_truncated"
+                : "rg_exhaustive",
             items,
             diagnostics: {
                 emptyReason,
-                fallback: rgResult.diagnostics,
+                rg: rgResult.diagnostics,
                 structure: structuralEnrichment.diagnostics,
             },
         };
     }
-    createRegistry(readOnly, embeddingModel = this.embeddingModel) {
-        return new CollectionRegistry(this.options.home, embeddingModel, readOnly);
+    openWorkspaceIndexForSearch(info, request, location, workspaceRuntime) {
+        return new WorkspaceIndex(info, this.embeddingModelForSearch(indexedEmbeddingSchema(info), request, workspaceRuntime, info), true, location.filesPath);
     }
-    openCollectionForSearch(info, request, registryHome) {
-        return new Collection(info, this.embeddingModelForSearch(indexedEmbeddingSchema(info), request, registryHome), true, join(registryHome, "files.zvec"));
-    }
-    embeddingModelForSearch(schema, request, registryHome) {
+    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, registryHome);
+        return this.recoverEmbeddingModel(schema, workspaceRuntime);
     }
-    embeddingModelForIndex(existing, registryHome, operation) {
-        if (isCollectionIndexed(existing) && !this.embeddingModelExplicit) {
-            return this.recoverEmbeddingModel(existing.embedding, registryHome);
+    embeddingModelForIndex(existing, operation, workspaceRuntime = {}) {
+        if (isWorkspaceIndexed(existing) &&
+            !this.embeddingModel &&
+            !this.options.embedding) {
+            return this.recoverEmbeddingModel(existing.embedding, workspaceRuntime);
         }
-        return this.requireEmbeddingModel(operation);
-    }
-    recoverEmbeddingModel(schema, registryHome) {
-        const key = `${schema.provider}/${schema.model}/${modelCacheDir(this.options, this.root, registryHome)}`;
+        const config = readGlobalConfig();
+        const reference = resolveEmbeddingReference({
+            explicit: this.options.embedding,
+            globalDefault: config.defaults?.embedding,
+            fallback: this.options.defaultEmbedding === true
+                ? DEFAULT_LOCAL_EMBEDDING
+                : undefined,
+        });
+        const referenceIdentity = reference
+            ? parseEmbeddingModelReference(reference)
+            : undefined;
+        const selectedWorkspaceRuntime = isWorkspaceIndexed(existing) &&
+            referenceIdentity &&
+            existing.embedding.provider !== referenceIdentity.provider
+            ? {}
+            : workspaceRuntime;
+        return (this.embeddingModel ??
+            (reference
+                ? this.embeddingModelFromReference(reference, config, selectedWorkspaceRuntime)
+                : undefined) ??
+            this.requireEmbeddingModel(operation));
+    }
+    recoverEmbeddingModel(schema, workspaceRuntime = {}) {
+        const config = readGlobalConfig();
+        const identity = {
+            provider: schema.provider,
+            name: schema.model,
+        };
+        const reference = embeddingModelReference(identity);
+        const options = providerOptions(this.options, identity, config, workspaceRuntime);
+        const key = `${reference}/${providerOptionsFingerprint(options)}`;
+        return this.cachedEmbeddingModel(key, () => createServiceEmbeddingModel(reference, options, this.options));
+    }
+    embeddingModelFromReference(reference, config = readGlobalConfig(), workspaceRuntime = {}) {
+        const identity = parseEmbeddingModelReference(reference);
+        const options = providerOptions(this.options, identity, config, workspaceRuntime);
+        const key = `configured/${reference}/${providerOptionsFingerprint(options)}`;
+        return this.cachedEmbeddingModel(key, () => createServiceEmbeddingModel(reference, options, this.options));
+    }
+    cachedEmbeddingModel(key, create) {
         const cached = this.recoveredEmbeddingModels.get(key);
         if (cached) {
+            this.recoveredEmbeddingModels.delete(key);
+            this.recoveredEmbeddingModels.set(key, cached);
             return cached;
         }
-        const model = createEmbeddingModel({
-            provider: schema.provider,
-            model: schema.model,
-        }, providerOptions(this.options, this.root, registryHome));
+        const model = create();
         this.recoveredEmbeddingModels.set(key, model);
+        this.trimRecoveredEmbeddingModels();
         return model;
     }
+    trimRecoveredEmbeddingModels() {
+        while (this.recoveredEmbeddingModels.size > MAX_RECOVERED_EMBEDDING_MODELS) {
+            const oldestKey = this.recoveredEmbeddingModels.keys().next().value;
+            if (oldestKey === undefined) {
+                return;
+            }
+            const model = this.recoveredEmbeddingModels.get(oldestKey);
+            this.recoveredEmbeddingModels.delete(oldestKey);
+            if (model) {
+                this.retiredEmbeddingModels.add(model);
+            }
+        }
+    }
+    async withEmbeddingModelOperation(operation) {
+        this.activeEmbeddingModelOperations += 1;
+        try {
+            return await operation();
+        }
+        finally {
+            this.activeEmbeddingModelOperations -= 1;
+            if (this.activeEmbeddingModelOperations === 0) {
+                await this.disposeRetiredEmbeddingModels();
+            }
+        }
+    }
+    async disposeRetiredEmbeddingModels() {
+        const models = [...this.retiredEmbeddingModels];
+        this.retiredEmbeddingModels.clear();
+        for (const model of models) {
+            await model.dispose();
+        }
+    }
     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>" or set ZVEC_GREP_EMBEDDING. Existing indexes can rerun --index without --embedding to reuse the stored schema.'),
+                    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/embeddinggemma-300m, qwen/text-embedding-v4"),
                 ]),
             });
@@ -522,6 +559,66 @@ class ZvecGrepService {
         }
     }
 }
+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 items = selectAndRankContextItems(searches.flatMap((search, index) => searchPlanToContextItems(search, input.root, groups[index])), 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,
+        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 {
@@ -540,22 +637,12 @@ async function withHomeWriteLock(home, operation, task) {
         lock.release();
     }
 }
-async function collectionNeedsRefresh(home, collectionName) {
-    const registry = new CollectionRegistry(home, undefined, true);
-    try {
-        const status = await registry.status(collectionName);
-        return status ? collectionIndexStatusNeedsRefresh(status) : false;
-    }
-    finally {
-        registry.close();
-    }
-}
-function collectionIndexStatusNeedsRefresh(status) {
-    return status.filesAdded > 0
-        || status.filesModified > 0
-        || status.filesDeleted > 0
-        || status.filesPending > 0
-        || status.filesFailed > 0;
+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 });
@@ -563,10 +650,10 @@ function acquireHomeLock(home, mode, operation) {
 function assertHomeUnlocked(home, operation) {
     assertNoWriteLock(homeLockPath(home), operation);
 }
-function assertNearestAnonymousHomeUnlocked(start, operation) {
+function assertNearestWorkspaceHomeUnlocked(start, operation) {
     let current = resolve(start);
     while (true) {
-        assertHomeUnlocked(anonymousHome(current), operation);
+        assertHomeUnlocked(workspaceHome(current), operation);
         const parent = dirname(current);
         if (parent === current) {
             return;
@@ -577,13 +664,11 @@ function assertNearestAnonymousHomeUnlocked(start, operation) {
 function homeLockPath(home) {
     return join(home, "locks", "home");
 }
-function serviceHome(options) {
-    return options.home ?? defaultHome();
-}
 function rgEmptyReason(diagnostics) {
-    return diagnostics.missingPaths && diagnostics.missingPaths.length > 0
-        && diagnostics.searchedPaths
-        && diagnostics.searchedPaths.length === 0
+    return diagnostics.missingPaths &&
+        diagnostics.missingPaths.length > 0 &&
+        diagnostics.searchedPaths &&
+        diagnostics.searchedPaths.length === 0
         ? "no_searchable_files"
         : "no_matches";
 }
@@ -600,71 +685,106 @@ function withContextTimings(result, timings) {
         },
     };
 }
-function findNearestAnonymousCollection(start) {
-    let current = resolve(start);
-    while (true) {
-        const location = anonymousIndexLocation(current);
-        const info = readCollectionInfo(location.home, ANONYMOUS_COLLECTION_NAME);
-        if (info) {
-            return { location, info };
-        }
-        const parent = dirname(current);
-        if (parent === current) {
-            return null;
-        }
-        current = parent;
-    }
+function findNearestWorkspaceIndex(start) {
+    const location = findNearestWorkspace(start);
+    if (!location)
+        return null;
+    const info = readWorkspaceManifest(location.home);
+    return info ? { location, info } : null;
 }
-function anonymousInfoSuggestion(collection) {
-    if (!collection) {
-        return "zg --index or zg --rg";
+function workspaceInfoSuggestion(workspaceIndex) {
+    if (!workspaceIndex) {
+        return "zg index or zg query --rg";
     }
-    if (collection.indexPolicy === "disabled") {
-        return "zg --rg";
+    if (workspaceIndex.indexPolicy === "disabled") {
+        return "zg query --rg";
     }
-    if (!isCollectionIndexed(collection)) {
-        return "zg --index";
+    if (!isWorkspaceIndexed(workspaceIndex)) {
+        return "zg index";
     }
     return undefined;
 }
-function anonymousIndexMissingError(root, policy) {
-    return new EngineError("No anonymous zvec-grep index found for this workspace", {
-        code: "ZVEC_GREP.ENGINE.SERVICE.ANONYMOUS_INDEX_NOT_FOUND",
+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."),
+                ? "Ask the user whether to build an index with zg index, or use zg query --rg for no-index search."
+                : "Run zg index to build the enabled workspace index, or use zg query --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 include/exclude filters; if no, run zg --disable-index. For immediate no-index search, use zg --rg."
-                : "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."),
+                ? "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 query --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 query --rg for immediate no-index search."),
         ]),
     });
 }
-function anonymousIndexDisabledError(root) {
-    return new EngineError("Anonymous zvec-grep index is disabled for this workspace", {
-        code: "ZVEC_GREP.ENGINE.SERVICE.ANONYMOUS_INDEX_DISABLED",
+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("hint", "Use zg query --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
-        ?? existing?.rootPaths
-        ?? [fallbackRoot];
+        ? inheritRequestedRootPathSettings(requested, existing?.rootPaths)
+        : (existing?.rootPaths ?? [fallbackRoot]);
     if (options.resetPaths) {
         rootPaths = rootPaths.map(resetRootPathFilters);
     }
-    if (options.includePaths !== undefined || options.excludePaths !== undefined) {
-        rootPaths = rootPaths.map((rootPath) => applyRootPathFilterOverrides(rootPath, options.includePaths, options.excludePaths));
+    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;
@@ -674,7 +794,7 @@ function resetRootPathFilters(rootPath) {
         recursive: rootPath.recursive,
     };
 }
-function applyRootPathFilterOverrides(rootPath, include, exclude) {
+function applyRootPathOverrides(rootPath, options) {
     const normalized = typeof rootPath === "string"
         ? {
             absolutePath: rootPath,
@@ -683,118 +803,230 @@ function applyRootPathFilterOverrides(rootPath, include, exclude) {
         : rootPath;
     return {
         ...normalized,
-        include: include ?? normalized.include,
-        exclude: exclude ?? normalized.exclude,
+        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 resolveEmbeddingModel(options, root) {
-    if (options.embeddingModel) {
-        return options.embeddingModel;
-    }
-    if (options.embedding) {
-        return createEmbeddingModelFromReference(options.embedding, providerOptions(options, root));
-    }
-    if (options.defaultEmbedding === true) {
-        return createEmbeddingModelFromReference(DEFAULT_LOCAL_EMBEDDING, providerOptions(options, root));
-    }
-    return undefined;
+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 hasExplicitEmbeddingModel(options) {
-    return options.embeddingModel !== undefined
-        || options.embedding !== undefined;
+function currentEmbeddingSchema(embeddingModel) {
+    return {
+        provider: embeddingModel.info.provider,
+        model: embeddingModel.info.name,
+        dimension: embeddingModel.info.dimension,
+        metric: embeddingModel.info.metric,
+    };
 }
-function readCollectionInfo(home, name) {
-    const registry = new CollectionRegistry(home, undefined, true);
+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, undefined, true, location.filesPath);
     try {
-        return registry.get(name);
+        return await workspaceIndex.status();
     }
     finally {
-        registry.close();
+        workspaceIndex.close();
     }
 }
 function indexedEmbeddingSchema(info) {
-    if (isCollectionIndexed(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([
-            collectionDetail(info.name),
-            detail("hint", "Run zg --index to build this index."),
+            workspaceIndexDetail(info.name),
+            detail("hint", "Run zg index to build this index."),
         ]),
     });
 }
-function providerOptions(options, root, registryHome) {
+function providerOptions(options, identity, config = readGlobalConfig(), workspaceRuntime = {}) {
+    const reference = embeddingModelReference(identity);
+    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,
+    };
+}
+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]))
+        .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: options.apiKey ?? "",
-        endpoint: options.endpoint,
-        modelCacheDir: modelCacheDir(options, root, registryHome),
-        llamaGpu: options.llamaGpu,
-        embeddingParallelism: options.embeddingParallelism,
+        apiKey: resolved.apiKey,
+        ...((model.info.endpoint ?? resolved.endpoint)
+            ? { endpoint: model.info.endpoint ?? resolved.endpoint }
+            : {}),
+        ...(model.info.provider === "local"
+            ? { device: resolved.device ?? "auto" }
+            : {}),
     };
 }
-function assertCollectionEmbeddingMatchesCurrentModel(info, model, rebuildCommand) {
-    if (!isCollectionIndexed(info)) {
+function runtimeForModelProvider(existing, model, workspaceRuntime) {
+    return isWorkspaceIndexed(existing) &&
+        existing.embedding.provider !== model.info.provider
+        ? {}
+        : workspaceRuntime;
+}
+function embeddingRuntimeAfterSuccessfulIndex(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.ref.provider
-        || expected.model !== model.ref.model
-        || expected.dimension !== model.dimension
-        || expected.metric !== model.metric;
+    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([
-            collectionDetail(info.name),
+            workspaceIndexDetail(info.name),
             detail("existing", `${expected.provider}/${expected.model}`),
-            detail("requested", `${model.ref.provider}/${model.ref.model}`),
+            detail("requested", model.info.reference),
             detail("hint", `Run "${rebuildCommand}" to rebuild this index with the requested embedding model.`),
         ]),
     });
 }
-function modelCacheDir(options, root, registryHome) {
-    if (options.modelCacheDir || process.env.ZVEC_GREP_MODEL_CACHE) {
-        return options.modelCacheDir ?? process.env.ZVEC_GREP_MODEL_CACHE;
-    }
-    const globalCache = join(options.home ?? defaultHome(), "models");
-    const legacyCaches = [
-        registryHome ? join(registryHome, "models") : undefined,
-        join(anonymousHome(root), "models"),
-    ];
-    const globalHasModel = directoryHasGguf(globalCache);
-    for (const legacyCache of legacyCaches) {
-        if (legacyCache && directoryHasGguf(legacyCache) && !globalHasModel) {
-            return legacyCache;
-        }
-    }
-    if (globalHasModel || canWriteCacheDirectory(globalCache)) {
-        return globalCache;
-    }
-    return join(anonymousHome(root), "models");
-}
-function directoryHasGguf(path) {
-    try {
-        return readdirSync(path, { withFileTypes: true }).some((entry) => entry.isFile() && entry.name.endsWith(".gguf"));
-    }
-    catch {
-        return false;
-    }
-}
-function canWriteCacheDirectory(path) {
-    const probe = join(path, `.zvec-grep-write-test-${Date.now()}-${Math.random().toString(16).slice(2)}`);
-    try {
-        mkdirSync(path, { recursive: true });
-        writeFileSync(probe, "");
-        unlinkSync(probe);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 function contextGroupLimit(limit, groupCount) {
     if (limit !== undefined) {
         return limit;
@@ -808,29 +1040,36 @@ function contextGroupLimit(limit, groupCount) {
 function normalizeContextRequest(options) {
     const primaryQueries = normalizePrimaryQueries(options.query, options.queries);
     const extraRoutes = normalizeContextRoutes(options.routes ?? []);
-    if (primaryQueries.length === 0 && extraRoutes.length === 0) {
+    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 fallbackQueries = groups.map((group) => group.fallbackQuery);
+    const rgPatterns = [
+        ...primaryQueries,
+        ...extraRoutes.map((route) => route.query),
+    ];
     const displayQuery = primaryQueries.length > 0
         ? primaryQueries.join(" | ")
-        : extraRoutes.map((route) => route.query).join(" | ");
+        : extraRoutes.length > 0
+            ? extraRoutes.map((route) => route.query).join(" | ")
+            : options
+                .rgOptions.patternFiles.map((path) => `@${path}`)
+                .join(" | ");
     return {
         displayQuery,
-        fallbackQueries,
+        rgPatterns,
         routes,
         groups,
     };
 }
 function normalizePrimaryQueries(query, queries) {
-    return [
-        query,
-        ...(queries ?? []),
-    ].flatMap((value) => {
+    return [query, ...(queries ?? [])].flatMap((value) => {
         const normalized = normalizeOptionalQuery(value);
         return normalized ? [normalized] : [];
     });
@@ -862,20 +1101,24 @@ function normalizeContextRoutes(routes) {
 }
 function contextGroups(primaryQueries, extraRoutes) {
     return [
-        ...primaryQueries.map((query) => ({
+        ...primaryQueries.map((query, index) => ({
+            id: `Q${index + 1}`,
+            query,
+            role: "primary",
             routes: [
                 { mode: "fts", query },
                 { mode: "vector", query },
             ],
-            fallbackQuery: query,
         })),
-        ...extraRoutes.map((route) => ({
+        ...extraRoutes.map((route, index) => ({
+            id: `Q${primaryQueries.length + index + 1}`,
+            query: route.query,
+            role: "supplemental",
             routes: [route],
-            fallbackQuery: route.query,
         })),
     ];
 }
-function searchPlanToContextItems(result, root) {
+function searchPlanToContextItems(result, root, group) {
     return result.hits.map((hit) => {
         const target = contextItemTarget(hit);
         return {
@@ -897,9 +1140,75 @@ function searchPlanToContextItems(result, root) {
             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_DETAIL_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 detailed = [];
+    for (const groupId of coverageGroupIds) {
+        if (detailed.length >= DEFAULT_CONTEXT_DETAIL_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));
+        detailed.push({
+            ...candidate,
+            selectionReason: "coverage",
+            coverageGroup: groupId,
+        });
+    }
+    for (const candidate of globallyRanked) {
+        if (detailed.length >= DEFAULT_CONTEXT_DETAIL_LIMIT) {
+            break;
+        }
+        const key = contextItemDedupeKey(candidate);
+        if (selected.has(key)) {
+            continue;
+        }
+        selected.add(key);
+        detailed.push({
+            ...candidate,
+            selectionReason: "global_fill",
+            coverageGroup: undefined,
+        });
+    }
+    const additional = globallyRanked.filter((item) => !selected.has(contextItemDedupeKey(item)));
+    return [...detailed, ...additional].map((item, index) => ({
+        ...item,
+        rank: index + 1,
+    }));
+}
 function dedupeAndRerankContextItems(items) {
     const seen = new Set();
     const deduped = [];
@@ -909,34 +1218,57 @@ function dedupeAndRerankContextItems(items) {
             continue;
         }
         seen.add(key);
-        deduped.push({
-            ...item,
-            rank: deduped.length + 1,
-        });
+        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 mergeFallbackDiagnostics(results) {
-    const [first] = results;
-    if (!first) {
-        throw new EngineError("zvec-grep lexical fallback requires at least one query", {
-            code: "ZVEC_GREP.ENGINE.SERVICE.EMPTY_QUERY",
-        });
-    }
-    return {
-        ...first.diagnostics,
-        truncated: results.some((result) => result.diagnostics.truncated),
-    };
+    return ["range", item.file.absolutePath, JSON.stringify(item.range)].join(":");
 }
 function contextItemTarget(hit) {
     const evidence = hit.evidence.find((item) => !item.isEntity);
@@ -979,7 +1311,8 @@ function contextItemOutline(hit, evidence) {
     if (!isUsefulOutline(hit.entity.metadata, outline)) {
         return undefined;
     }
-    if (evidence?.content.kind === "text" && evidence.content.text.trim() === outline) {
+    if (evidence?.content.kind === "text" &&
+        evidence.content.text.trim() === outline) {
         return undefined;
     }
     return outline;
@@ -988,23 +1321,23 @@ function isUsefulOutline(metadata, outline) {
     if (!metadata || metadata.kind !== "code") {
         return false;
     }
-    return metadata.symbolType === "class"
-        || metadata.symbolType === "interface"
-        || metadata.symbolType === "module"
-        || outline.includes("\ncalls:");
+    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);
+    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 === "image" &&
+            left.format === right.format &&
+            left.data.byteLength === right.data.byteLength);
     }
     return right.kind === "text" && left.text === right.text;
 }
@@ -1020,7 +1353,8 @@ function fileFreshnessStatus(file) {
         if (file.indexStatus.indexedTime >= info.mtimeMs) {
             return "fresh";
         }
-        if (file.contentHash && sha256File(file.absolutePath) === file.contentHash) {
+        if (file.contentHash &&
+            sha256File(file.absolutePath) === file.contentHash) {
             return "fresh";
         }
     }