feat: add index metadata contract to prevent incompatible provider searches

Store embedding provider, model, and dimensions in SQLite metadata.
Refuse to search if current provider is incompatible with indexed data.
User must run index with force=true to rebuild when provider changes.

Author: Helweg

README.md

@@ -131,6 +131,7 @@ graph TD
 - **Native speed**: Core logic written in Rust for maximum performance
 - **Memory efficient**: F16 vector quantization reduces index size by 50%
 - **Branch-aware**: Automatically tracks which chunks exist on each git branch
+- **Provider validation**: Detects embedding provider/model changes and requires rebuild to prevent garbage results
 
 ## 🌿 Branch-Aware Indexing
 

TROUBLESHOOTING.md

@@ -8,6 +8,7 @@ Common issues and solutions for opencode-codebase-index.
 - [No Embedding Provider Available](#no-embedding-provider-available)
 - [Rate Limiting Errors](#rate-limiting-errors)
 - [Index Corruption / Stale Results](#index-corruption--stale-results)
+- [Embedding Provider Changed](#embedding-provider-changed)
 - [Native Module Build Failures](#native-module-build-failures)
 - [Slow Indexing Performance](#slow-indexing-performance)
 - [Search Returns No Results](#search-returns-no-results)
@@ -189,6 +190,47 @@ The next `/index` will rebuild from scratch.
 
 ---
 
+## Embedding Provider Changed
+
+**Error message:**
+```
+Index incompatible: <reason>. Run index with force=true to rebuild.
+```
+
+**Cause:** The index was built with a different embedding provider or model than what's currently configured. Embeddings from different providers have different dimensions and are not compatible.
+
+**Common scenarios:**
+- Switched from GitHub Copilot to OpenAI
+- Changed Ollama embedding model
+- Updated to a new version of the embedding model
+
+**Solutions:**
+
+### Force Re-index
+Ask the agent:
+> "Force reindex the codebase"
+
+Or run `/index` with the force option. This will:
+1. Delete all existing embeddings
+2. Re-index all files with the new provider
+
+### Why This Happens
+Different embedding providers produce vectors with different dimensions:
+
+| Provider | Model | Dimensions |
+|----------|-------|------------|
+| GitHub Copilot | text-embedding-3-small | 1536 |
+| OpenAI | text-embedding-3-small | 1536 |
+| Google | text-embedding-004 | 768 |
+| Ollama | nomic-embed-text | 768 |
+
+Mixing embeddings from different providers would produce garbage search results, so the plugin refuses to search until you rebuild the index.
+
+### Check Current Index Metadata
+Run `/status` to see what provider/model the index was built with.
+
+---
+
 ## Native Module Build Failures
 
 **Error messages:**
@@ -395,6 +437,7 @@ If none of these solutions work:
 | No provider | `export OPENAI_API_KEY=...` or use Ollama |
 | Rate limited | Switch to Ollama for large codebases |
 | Stale results | `rm -rf .opencode/index/` and re-index |
+| Provider changed | Force re-index: ask agent to "force reindex" |
 | Slow indexing | Use Ollama locally |
 | No results | Run `/index` first, use descriptive queries |
 | Native module error | Rebuild with Rust toolchain |

src/indexer/index.ts

@@ -95,6 +95,26 @@ interface FailedBatch {
   lastAttempt: string;
 }
 
+interface IndexMetadata {
+  indexVersion: string;
+  embeddingProvider: string;
+  embeddingModel: string;
+  embeddingDimensions: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface IndexCompatibility {
+  compatible: boolean;
+  reason?: string;
+  storedMetadata?: IndexMetadata;
+  currentProvider?: string;
+  currentModel?: string;
+  currentDimensions?: number;
+}
+
+const INDEX_METADATA_VERSION = "1";
+
 export class Indexer {
   private config: ParsedCodebaseIndexConfig;
   private projectRoot: string;
@@ -114,6 +134,7 @@ export class Indexer {
   private readonly maxQueryCacheSize = 100;
   private readonly queryCacheTtlMs = 5 * 60 * 1000;
   private readonly querySimilarityThreshold = 0.85;
+  private indexCompatibility: IndexCompatibility | null = null;
 
   constructor(projectRoot: string, config: ParsedCodebaseIndexConfig) {
     this.projectRoot = projectRoot;
@@ -254,6 +275,19 @@ export class Indexer {
       this.migrateFromLegacyIndex();
     }
 
+    this.indexCompatibility = this.validateIndexCompatibility(this.detectedProvider);
+    if (!this.indexCompatibility.compatible) {
+      this.logger.warn("Index compatibility issue detected", {
+        reason: this.indexCompatibility.reason,
+        storedProvider: this.indexCompatibility.storedMetadata?.embeddingProvider,
+        storedModel: this.indexCompatibility.storedMetadata?.embeddingModel,
+        storedDimensions: this.indexCompatibility.storedMetadata?.embeddingDimensions,
+        currentProvider: this.indexCompatibility.currentProvider,
+        currentModel: this.indexCompatibility.currentModel,
+        currentDimensions: this.indexCompatibility.currentDimensions,
+      });
+    }
+
     if (isGitRepo(this.projectRoot)) {
       this.currentBranch = getBranchOrDefault(this.projectRoot);
       this.baseBranch = getBaseBranch(this.projectRoot);
@@ -339,6 +373,92 @@ export class Indexer {
     this.database.addChunksToBranchBatch(this.currentBranch || "default", chunkIds);
   }
 
+  private loadIndexMetadata(): IndexMetadata | null {
+    if (!this.database) return null;
+
+    const version = this.database.getMetadata("index.version");
+    if (!version) return null;
+
+    return {
+      indexVersion: version,
+      embeddingProvider: this.database.getMetadata("index.embeddingProvider") ?? "",
+      embeddingModel: this.database.getMetadata("index.embeddingModel") ?? "",
+      embeddingDimensions: parseInt(this.database.getMetadata("index.embeddingDimensions") ?? "0", 10),
+      createdAt: this.database.getMetadata("index.createdAt") ?? "",
+      updatedAt: this.database.getMetadata("index.updatedAt") ?? "",
+    };
+  }
+
+  private saveIndexMetadata(provider: DetectedProvider): void {
+    if (!this.database) return;
+
+    const now = new Date().toISOString();
+    const existingCreatedAt = this.database.getMetadata("index.createdAt");
+
+    this.database.setMetadata("index.version", INDEX_METADATA_VERSION);
+    this.database.setMetadata("index.embeddingProvider", provider.provider);
+    this.database.setMetadata("index.embeddingModel", provider.modelInfo.model);
+    this.database.setMetadata("index.embeddingDimensions", provider.modelInfo.dimensions.toString());
+    this.database.setMetadata("index.updatedAt", now);
+
+    if (!existingCreatedAt) {
+      this.database.setMetadata("index.createdAt", now);
+    }
+  }
+
+  private validateIndexCompatibility(provider: DetectedProvider): IndexCompatibility {
+    const storedMetadata = this.loadIndexMetadata();
+
+    if (!storedMetadata) {
+      return { compatible: true };
+    }
+
+    const currentProvider = provider.provider;
+    const currentModel = provider.modelInfo.model;
+    const currentDimensions = provider.modelInfo.dimensions;
+
+    if (storedMetadata.embeddingDimensions !== currentDimensions) {
+      return {
+        compatible: false,
+        reason: `Dimension mismatch: index has ${storedMetadata.embeddingDimensions}D vectors (${storedMetadata.embeddingProvider}/${storedMetadata.embeddingModel}), but current provider uses ${currentDimensions}D (${currentProvider}/${currentModel}). Run "index --force" to rebuild.`,
+        storedMetadata,
+        currentProvider,
+        currentModel,
+        currentDimensions,
+      };
+    }
+
+    if (storedMetadata.embeddingModel !== currentModel) {
+      return {
+        compatible: false,
+        reason: `Model mismatch: index was built with "${storedMetadata.embeddingModel}", but current model is "${currentModel}". Embeddings may be incompatible. Run "index --force" to rebuild.`,
+        storedMetadata,
+        currentProvider,
+        currentModel,
+        currentDimensions,
+      };
+    }
+
+    return {
+      compatible: true,
+      storedMetadata,
+      currentProvider,
+      currentModel,
+      currentDimensions,
+    };
+  }
+
+  checkCompatibility(): IndexCompatibility {
+    if (this.indexCompatibility) {
+      return this.indexCompatibility;
+    }
+    return { compatible: true };
+  }
+
+  requiresRebuild(): boolean {
+    return !this.checkCompatibility().compatible;
+  }
+
   private async ensureInitialized(): Promise<{
     store: VectorStore;
     provider: EmbeddingProviderInterface;
@@ -750,6 +870,9 @@ export class Indexer {
 
     stats.durationMs = Date.now() - startTime;
 
+    this.saveIndexMetadata(detectedProvider);
+    this.indexCompatibility = { compatible: true };
+
     this.logger.recordIndexingEnd();
     this.logger.info("Indexing complete", {
       files: stats.totalFiles,
@@ -884,6 +1007,11 @@ export class Indexer {
       name?: string;
     }>
   > {
+    const compatibility = this.checkCompatibility();
+    if (!compatibility.compatible) {
+      throw new Error(compatibility.reason ?? "Index is incompatible with current embedding provider");
+    }
+
     const searchStartTime = performance.now();
     const { store, provider, database } = await this.ensureInitialized();
 

tests/database.test.ts

@@ -208,6 +208,46 @@ describe("Database", () => {
     });
   });
 
+  describe("index metadata contract", () => {
+    it("should store index metadata fields", () => {
+      db.setMetadata("index.version", "1");
+      db.setMetadata("index.embeddingProvider", "openai");
+      db.setMetadata("index.embeddingModel", "text-embedding-3-small");
+      db.setMetadata("index.embeddingDimensions", "1536");
+      db.setMetadata("index.createdAt", "2025-01-19T00:00:00Z");
+      db.setMetadata("index.updatedAt", "2025-01-19T00:00:00Z");
+
+      expect(db.getMetadata("index.version")).toBe("1");
+      expect(db.getMetadata("index.embeddingProvider")).toBe("openai");
+      expect(db.getMetadata("index.embeddingModel")).toBe("text-embedding-3-small");
+      expect(db.getMetadata("index.embeddingDimensions")).toBe("1536");
+    });
+
+    it("should persist index metadata across database reopening", () => {
+      const dbPath = path.join(tempDir, "persist-test.db");
+      const db1 = new Database(dbPath);
+      
+      db1.setMetadata("index.embeddingProvider", "ollama");
+      db1.setMetadata("index.embeddingDimensions", "768");
+      
+      const db2 = new Database(dbPath);
+      
+      expect(db2.getMetadata("index.embeddingProvider")).toBe("ollama");
+      expect(db2.getMetadata("index.embeddingDimensions")).toBe("768");
+    });
+
+    it("should update index metadata on reindex", () => {
+      db.setMetadata("index.embeddingProvider", "openai");
+      db.setMetadata("index.embeddingDimensions", "1536");
+      db.setMetadata("index.updatedAt", "2025-01-18T00:00:00Z");
+
+      db.setMetadata("index.updatedAt", "2025-01-19T12:00:00Z");
+
+      expect(db.getMetadata("index.embeddingProvider")).toBe("openai");
+      expect(db.getMetadata("index.updatedAt")).toBe("2025-01-19T12:00:00Z");
+    });
+  });
+
   describe("garbage collection", () => {
     it("should gc orphan embeddings", () => {
       const embedding = Buffer.from(new Float32Array([1.0]).buffer);