feat(06-01): gate index consumers on IndexMeta validation

- Validate index-meta + artifacts before serving any index-derived data
- Fail closed on legacy/corrupt keyword index to trigger auto-heal
- Attach index status/confidence/action metadata to index-consuming responses

Author: PatrickSys

src/analyzers/angular/index.ts

@@ -885,11 +885,17 @@ export class AngularAnalyzer implements FrameworkAnalyzer {
     try {
       const indexPath = path.join(rootPath, CODEBASE_CONTEXT_DIRNAME, KEYWORD_INDEX_FILENAME);
       const indexContent = await fs.readFile(indexPath, 'utf-8');
-      const chunks = JSON.parse(indexContent);
+      const parsed = JSON.parse(indexContent) as any;
 
-      console.error(`Loading statistics from ${indexPath}: ${chunks.length} chunks`);
+      // Legacy index.json is an array — do not consume it (missing version/meta headers).
+      if (Array.isArray(parsed)) {
+        return metadata;
+      }
 
+      const chunks = parsed && Array.isArray(parsed.chunks) ? parsed.chunks : null;
       if (Array.isArray(chunks) && chunks.length > 0) {
+        console.error(`Loading statistics from ${indexPath}: ${chunks.length} chunks`);
+
         metadata.statistics.totalFiles = new Set(chunks.map((c: any) => c.filePath)).size;
         metadata.statistics.totalLines = chunks.reduce(
           (sum: number, c: any) => sum + (c.endLine - c.startLine + 1),

src/core/indexer.ts

@@ -873,7 +873,12 @@ export class CodebaseIndexer {
         INTELLIGENCE_FILENAME
       );
       const intelligenceContent = await fs.readFile(intelligencePath, 'utf-8');
-      const intelligence = JSON.parse(intelligenceContent);
+      const intelligence = JSON.parse(intelligenceContent) as any;
+
+      // Phase 06: ignore legacy intelligence files that lack a versioned header.
+      if (!intelligence || typeof intelligence !== 'object' || !intelligence.header) {
+        return metadata;
+      }
 
       metadata.customMetadata = {
         ...metadata.customMetadata,

src/core/search.ts

@@ -14,6 +14,7 @@ import { IndexCorruptedError } from '../errors/index.js';
 import { isTestingRelatedQuery } from '../preflight/query-scope.js';
 import { assessSearchQuality } from './search-quality.js';
 import { rerank } from './reranker.js';
+import { type IndexMeta, readIndexMeta, validateIndexArtifacts } from './index-meta.js';
 import {
   CODEBASE_CONTEXT_DIRNAME,
   INTELLIGENCE_FILENAME,
@@ -112,6 +113,8 @@ export class CodebaseSearcher {
   private rootPath: string;
   private storagePath: string;
 
+  private indexMeta: IndexMeta | null = null;
+
   private fuseIndex: Fuse<CodeChunk> | null = null;
   private chunks: CodeChunk[] = [];
 
@@ -138,6 +141,10 @@ export class CodebaseSearcher {
     if (this.initialized) return;
 
     try {
+      // Fail closed on version mismatch/corruption before serving any results.
+      this.indexMeta = await readIndexMeta(this.rootPath);
+      await validateIndexArtifacts(this.rootPath, this.indexMeta);
+
       await this.loadKeywordIndex();
       await this.loadPatternIntelligence();
 
@@ -160,7 +167,20 @@ export class CodebaseSearcher {
     try {
       const indexPath = path.join(this.rootPath, CODEBASE_CONTEXT_DIRNAME, KEYWORD_INDEX_FILENAME);
       const content = await fs.readFile(indexPath, 'utf-8');
-      this.chunks = JSON.parse(content);
+      const parsed = JSON.parse(content) as any;
+
+      if (Array.isArray(parsed)) {
+        throw new IndexCorruptedError(
+          'Legacy keyword index format detected (missing header). Rebuild required.'
+        );
+      }
+
+      const chunks = parsed && Array.isArray(parsed.chunks) ? parsed.chunks : null;
+      if (!chunks) {
+        throw new IndexCorruptedError('Keyword index corrupted: expected { header, chunks }');
+      }
+
+      this.chunks = chunks;
 
       this.fuseIndex = new Fuse(this.chunks, {
         keys: [
@@ -178,9 +198,12 @@ export class CodebaseSearcher {
         ignoreLocation: true
       });
     } catch (error) {
-      console.warn('Keyword index load failed:', error);
-      this.chunks = [];
-      this.fuseIndex = null;
+      if (error instanceof IndexCorruptedError) {
+        throw error;
+      }
+      throw new IndexCorruptedError(
+        `Keyword index load failed (rebuild required): ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
 

src/core/symbol-references.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { CODEBASE_CONTEXT_DIRNAME, KEYWORD_INDEX_FILENAME } from '../constants/codebase-context.js';
+import { IndexCorruptedError } from '../errors/index.js';
 
 interface IndexedChunk {
   content?: unknown;
@@ -78,18 +79,27 @@ export async function findSymbolReferences(
   try {
     const content = await fs.readFile(indexPath, 'utf-8');
     chunksRaw = JSON.parse(content);
-  } catch {
-    return {
-      status: 'error',
-      message: 'Run indexing first'
-    };
+  } catch (error) {
+    throw new IndexCorruptedError(
+      `Keyword index missing or unreadable (rebuild required): ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
   }
 
-  if (!Array.isArray(chunksRaw)) {
-    return {
-      status: 'error',
-      message: 'Run indexing first'
-    };
+  if (Array.isArray(chunksRaw)) {
+    throw new IndexCorruptedError(
+      'Legacy keyword index format detected (missing header). Rebuild required.'
+    );
+  }
+
+  const chunks =
+    chunksRaw && typeof chunksRaw === 'object' && Array.isArray((chunksRaw as any).chunks)
+      ? ((chunksRaw as any).chunks as unknown[])
+      : null;
+
+  if (!chunks) {
+    throw new IndexCorruptedError('Keyword index corrupted: expected { header, chunks }');
   }
 
   const usages: SymbolUsage[] = [];
@@ -98,7 +108,7 @@ export async function findSymbolReferences(
   const escapedSymbol = escapeRegex(normalizedSymbol);
   const matcher = new RegExp(`\\b${escapedSymbol}\\b`, 'g');
 
-  for (const chunkRaw of chunksRaw) {
+  for (const chunkRaw of chunks) {
     const chunk = chunkRaw as IndexedChunk;
     if (typeof chunk.content !== 'string') {
       continue;