@zvec/zvec-grep 0.1.5 → 0.1.6

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

@@ -1,27 +1,87 @@
-import { mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
-import { createHash } from "node:crypto";
-import { dirname, join, relative, resolve } from "node:path";
-import { globalConfigPath, readGlobalConfig, } from "../config.js";
-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 { 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;
     recoveredEmbeddingModels = new Map();
     retiredEmbeddingModels = new Set();
@@ -31,23 +91,21 @@ class ZvecGrepService {
         this.options = options;
         this.root = resolveZvecGrepRoot(options.root);
         this.embeddingModel = options.embeddingModel;
-        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),
-        };
     }
     async index(options = {}) {
         this.ensureOpen();
         const root = resolveZvecGrepRoot(options.root ?? this.root);
-        const location = anonymousIndexLocation(root);
-        return await this.withEmbeddingModelOperation(() => 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,
@@ -63,56 +121,100 @@ class ZvecGrepService {
                     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 location = anonymousIndexLocation(root);
-        if (!readCollectionInfo(location.home, ANONYMOUS_COLLECTION_NAME)) {
-            return false;
-        }
-        return await withHomeWriteLock(location.home, "index.drop", async () => {
-            const registry = new CollectionRegistry(location.home, undefined);
-            try {
-                return registry.remove(ANONYMOUS_COLLECTION_NAME);
-            }
-            finally {
-                registry.close();
+        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();
@@ -124,76 +226,73 @@ class ZvecGrepService {
     }
     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 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,
         ]);
@@ -204,248 +303,83 @@ class ZvecGrepService {
         }
         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 this.withEmbeddingModelOperation(() => 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,
-                    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(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,
-                        },
-                        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 groups = input.options.fuse
-            ? [{ routes: input.request.routes }]
-            : input.request.groups;
-        const limit = contextGroupLimit(input.options.limit, groups.length);
-        for (const group of 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,
-                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 = 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),
-                },
-            },
-        };
+        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;
@@ -497,60 +431,68 @@ class ZvecGrepService {
             },
         };
     }
-    createRegistry(readOnly, embeddingModel = this.embeddingModel) {
-        return new CollectionRegistry(this.options.home, embeddingModel, readOnly);
-    }
-    openCollectionForSearch(info, request, registryHome) {
-        return new Collection(info, this.embeddingModelForSearch(indexedEmbeddingSchema(info), request, registryHome), true, join(registryHome, "files.zvec"));
+    openWorkspaceIndexForSearch(info, request, location, workspaceRuntime) {
+        return new WorkspaceIndex(info, this.embeddingModelForSearch(indexedEmbeddingSchema(info), request, workspaceRuntime, info), true, location.filesPath);
     }
-    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) &&
+    embeddingModelForIndex(existing, operation, workspaceRuntime = {}) {
+        if (isWorkspaceIndexed(existing) &&
             !this.embeddingModel &&
             !this.options.embedding) {
-            return this.recoverEmbeddingModel(existing.embedding, registryHome);
+            return this.recoverEmbeddingModel(existing.embedding, workspaceRuntime);
         }
-        const reference = this.options.embedding ??
-            (this.options.defaultEmbedding === true
+        const config = readGlobalConfig();
+        const reference = resolveEmbeddingReference({
+            explicit: this.options.embedding,
+            globalDefault: config.defaults?.embedding,
+            fallback: this.options.defaultEmbedding === true
                 ? DEFAULT_LOCAL_EMBEDDING
-                : undefined);
+                : 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, registryHome)
+                ? this.embeddingModelFromReference(reference, config, selectedWorkspaceRuntime)
                 : undefined) ??
-            this.configuredEmbeddingModel(registryHome) ??
             this.requireEmbeddingModel(operation));
     }
-    recoverEmbeddingModel(schema, registryHome) {
+    recoverEmbeddingModel(schema, workspaceRuntime = {}) {
         const config = readGlobalConfig();
-        const options = providerOptions(this.options, this.root, registryHome, schema.provider, config);
-        const key = `${schema.provider}/${schema.model}/${providerOptionsFingerprint(options)}`;
-        return this.cachedEmbeddingModel(key, () => createEmbeddingModel({
+        const identity = {
             provider: schema.provider,
-            model: schema.model,
-        }, options));
-    }
-    configuredEmbeddingModel(registryHome) {
-        const config = readGlobalConfig();
-        const reference = config.defaults?.embedding;
-        if (!reference) {
-            return undefined;
-        }
-        return this.embeddingModelFromReference(reference, registryHome, config);
-    }
-    embeddingModelFromReference(reference, registryHome, config = readGlobalConfig()) {
-        const provider = providerFromReference(reference);
-        const options = providerOptions(this.options, this.root, registryHome, provider, config);
+            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, () => createEmbeddingModelFromReference(reference, options));
+        return this.cachedEmbeddingModel(key, () => createServiceEmbeddingModel(reference, options, this.options));
     }
     cachedEmbeddingModel(key, create) {
         const cached = this.recoveredEmbeddingModels.get(key);
@@ -617,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 {
@@ -635,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 });
@@ -658,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;
@@ -672,9 +664,6 @@ 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 &&
@@ -696,36 +685,28 @@ 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) {
+function workspaceInfoSuggestion(workspaceIndex) {
+    if (!workspaceIndex) {
         return "zg index or zg query --rg";
     }
-    if (collection.indexPolicy === "disabled") {
+    if (workspaceIndex.indexPolicy === "disabled") {
         return "zg query --rg";
     }
-    if (!isCollectionIndexed(collection)) {
+    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),
@@ -738,9 +719,9 @@ function anonymousIndexMissingError(root, policy) {
         ]),
     });
 }
-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"),
@@ -836,117 +817,216 @@ function applyRootPathOverrides(rootPath, options) {
         follow: options.follow ?? normalized.follow,
     };
 }
-function readCollectionInfo(home, name) {
-    const registry = new CollectionRegistry(home, undefined, true);
+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, 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),
+            workspaceIndexDetail(info.name),
             detail("hint", "Run zg index to build this index."),
         ]),
     });
 }
-function providerOptions(options, root, registryHome, provider, config = readGlobalConfig()) {
-    const providerConfig = provider ? config.providers?.[provider] : undefined;
+function providerOptions(options, identity, config = readGlobalConfig(), workspaceRuntime = {}) {
+    const reference = embeddingModelReference(identity);
+    const runtime = resolveEmbeddingRuntimeOptions(reference, options, workspaceRuntime, config);
     return {
-        apiKey: options.apiKey ?? providerConfig?.apiKey ?? "",
-        endpoint: options.endpoint ?? providerConfig?.endpoint,
+        apiKey: runtime.apiKey,
+        endpoint: runtime.endpoint,
         modelCacheDir: options.modelCacheDir ??
-            process.env.ZVEC_GREP_MODEL_CACHE ??
             config.defaults?.modelCacheDir ??
-            modelCacheDir(options, root, registryHome),
-        llamaGpu: options.llamaGpu ?? config.defaults?.llamaGpu,
-        embeddingParallelism: options.embeddingParallelism ?? config.defaults?.embeddingParallelism,
+            process.env.ZVEC_GREP_MODEL_CACHE ??
+            join(options.home ?? defaultHome(), "models"),
+        device: runtime.device,
     };
 }
-function providerFromReference(reference) {
+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("/");
-    return separator > 0 ? reference.slice(0, separator) : undefined;
+    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) {
-    return createHash("sha256")
-        .update(JSON.stringify([
-        options.apiKey,
-        options.endpoint,
-        options.modelCacheDir,
-        options.llamaGpu,
-        options.embeddingParallelism,
-    ]))
+    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 assertCollectionEmbeddingMatchesCurrentModel(info, model, rebuildCommand) {
-    if (!isCollectionIndexed(info)) {
+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 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;
@@ -1021,18 +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 },
             ],
         })),
-        ...extraRoutes.map((route) => ({
+        ...extraRoutes.map((route, index) => ({
+            id: `Q${primaryQueries.length + index + 1}`,
+            query: route.query,
+            role: "supplemental",
             routes: [route],
         })),
     ];
 }
-function searchPlanToContextItems(result, root) {
+function searchPlanToContextItems(result, root, group) {
     return result.hits.map((hit) => {
         const target = contextItemTarget(hit);
         return {
@@ -1054,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 = [];
@@ -1066,13 +1218,52 @@ 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}`;