@softerist/heuristic-mcp 3.2.2 → 3.2.3

package/features/lifecycle.js

@@ -1269,6 +1269,36 @@ export async function status({ fix = false, cacheOnly = false, workspaceDir = nu
             if (binaryTelemetry.lastError?.message) {
               console.info(`   Last binary error: ${binaryTelemetry.lastError.message}`);
             }
+            if (
+              (totals.corruptionDetected || 0) > 0 ||
+              (totals.corruptionAutoCleared || 0) > 0 ||
+              (totals.corruptionSecondaryReadonlyBlocked || 0) > 0
+            ) {
+              console.info(
+                `   Corruption telemetry: detected=${totals.corruptionDetected || 0} autoCleared=${totals.corruptionAutoCleared || 0} secondaryBlocked=${totals.corruptionSecondaryReadonlyBlocked || 0}`
+              );
+            }
+            if (binaryTelemetry.lastCorruption?.at || binaryTelemetry.lastCorruption?.message) {
+              const atLabel = binaryTelemetry.lastCorruption?.at
+                ? formatDateTime(binaryTelemetry.lastCorruption.at)
+                : 'unknown time';
+              const actionLabel =
+                typeof binaryTelemetry.lastCorruption?.action === 'string'
+                  ? binaryTelemetry.lastCorruption.action
+                  : 'unknown';
+              const contextLabel =
+                typeof binaryTelemetry.lastCorruption?.context === 'string'
+                  ? binaryTelemetry.lastCorruption.context
+                  : 'n/a';
+              const msgLabel =
+                typeof binaryTelemetry.lastCorruption?.message === 'string' &&
+                binaryTelemetry.lastCorruption.message.trim().length > 0
+                  ? ` message=${binaryTelemetry.lastCorruption.message}`
+                  : '';
+              console.info(
+                `   Last corruption event: ${atLabel} action=${actionLabel} context=${contextLabel}${msgLabel}`
+              );
+            }
           }
 
           if (metaData && isProgressIncomplete) {

package/index.js

@@ -50,7 +50,7 @@ import {
 } from './lib/server-lifecycle.js';
 
 import { EmbeddingsCache } from './lib/cache.js';
-import { cleanupStaleBinaryArtifacts } from './lib/vector-store-binary.js';
+import { cleanupStaleBinaryArtifacts, recordBinaryStoreCorruption } from './lib/vector-store-binary.js';
 import { CodebaseIndexer } from './features/index-codebase.js';
 import { HybridSearch } from './features/hybrid-search.js';
 
@@ -879,7 +879,25 @@ async function initialize(workspaceDir) {
         stopStartupMemory();
       }
     };
-    const tryAutoAttachWorkspaceCache = async (reason) => {
+    const handleCorruptCacheAfterLoad = async ({ context, canReindex }) => {
+      if (!cache.consumeAutoReindex()) return false;
+      cache.clearInMemoryState();
+      await recordBinaryStoreCorruption(config.cacheDirectory, {
+        context,
+        action: canReindex ? 'auto-cleared' : 'secondary-readonly-blocked',
+      });
+      if (canReindex) {
+        console.warn(
+          `[Server] Cache corruption detected while ${context}; in-memory cache was cleared and a full re-index will run.`
+        );
+      } else {
+        console.warn(
+          `[Server] Cache corruption detected while ${context}. This server is secondary read-only and cannot re-index. Reload the IDE window for this workspace or use the primary instance to rebuild the cache.`
+        );
+      }
+      return true;
+    };
+    const tryAutoAttachWorkspaceCache = async (reason, { canReindex = workspaceLockAcquired } = {}) => {
       const candidate = await findAutoAttachWorkspaceCandidate({
         excludeCacheDirectory: config.cacheDirectory,
       });
@@ -897,6 +915,10 @@ async function initialize(workspaceDir) {
         await cleanupStaleBinaryArtifacts(config.cacheDirectory, { logger: console });
       }
       await cache.load();
+      await handleCorruptCacheAfterLoad({
+        context: `auto-attaching workspace cache (${reason})`,
+        canReindex,
+      });
       console.info(
         `[Server] Auto-attached workspace cache (${reason}): ${candidate.workspace} via ${candidate.source}`
       );
@@ -916,7 +938,9 @@ async function initialize(workspaceDir) {
         console.warn(
           `[Server] Detected system fallback workspace: ${config.searchDirectory}. Attempting cache auto-attach.`
         );
-        const attached = await tryAutoAttachWorkspaceCache('system-fallback');
+        const attached = await tryAutoAttachWorkspaceCache('system-fallback', {
+          canReindex: workspaceLockAcquired,
+        });
         if (!attached) {
           console.warn(
             '[Server] Waiting for a proper workspace root (MCP roots, env vars, or f_set_workspace).'
@@ -932,8 +956,12 @@ async function initialize(workspaceDir) {
       try {
         console.info('[Server] Secondary instance detected; loading cache in read-only mode.');
         await cache.load();
+        await handleCorruptCacheAfterLoad({
+          context: 'loading cache in secondary read-only mode',
+          canReindex: false,
+        });
         if (cache.getStoreSize() === 0) {
-          await tryAutoAttachWorkspaceCache('secondary-empty-cache');
+          await tryAutoAttachWorkspaceCache('secondary-empty-cache', { canReindex: false });
         }
         if (config.verbose) {
           logMemory('[Server] Memory (after cache load)');
@@ -947,9 +975,10 @@ async function initialize(workspaceDir) {
 
     void preloadEmbeddingModel();
 
-    try {
-      console.info('[Server] Loading cache (deferred)...');
+    try {
+      console.info('[Server] Loading cache (deferred)...');
       await cache.load();
+      await handleCorruptCacheAfterLoad({ context: 'startup cache load', canReindex: true });
       if (config.verbose) {
         logMemory('[Server] Memory (after cache load)');
       }
@@ -1105,6 +1134,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
       await fs.mkdir(config.cacheDirectory, { recursive: true });
       await cache.load();
+      if (cache.consumeAutoReindex()) {
+        cache.clearInMemoryState();
+        await recordBinaryStoreCorruption(config.cacheDirectory, {
+          context: 'f_set_workspace read-only attach',
+          action: 'secondary-readonly-blocked',
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Attached cache for ${normalizedPath}, but it is corrupt. This secondary read-only instance cannot rebuild it. Reload the IDE window for this workspace or run indexing from the primary instance.`,
+            },
+          ],
+          isError: true,
+        };
+      }
       trustWorkspacePath(normalizedPath);
       return {
         content: [

package/lib/cache.js

@@ -1,14 +1,18 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { Worker } from 'worker_threads';
-import { StreamingJsonWriter } from './json-writer.js';
-import { BinaryVectorStore } from './vector-store-binary.js';
-import { SqliteVectorStore } from './vector-store-sqlite.js';
-import { isNonProjectDirectory } from './config.js';
+import { Worker } from 'worker_threads';
+import { StreamingJsonWriter } from './json-writer.js';
 import {
-  JSON_WORKER_THRESHOLD_BYTES,
-  ANN_DIMENSION_SAMPLE_SIZE,
-  HNSWLIB_ERROR_RESET_MS,
+  BinaryVectorStore,
+  BinaryStoreCorruptionError,
+  recordBinaryStoreCorruption,
+} from './vector-store-binary.js';
+import { SqliteVectorStore } from './vector-store-sqlite.js';
+import { isNonProjectDirectory } from './config.js';
+import {
+  JSON_WORKER_THRESHOLD_BYTES,
+  ANN_DIMENSION_SAMPLE_SIZE,
+  HNSWLIB_ERROR_RESET_MS,
   DEFAULT_READER_WAIT_TIMEOUT_MS,
 } from './constants.js';
 
@@ -266,12 +270,12 @@ export class EmbeddingsCache {
     };
 
     
-    this.saveQueue = Promise.resolve();
-    this._saveTimer = null;
-    this._saveRequested = false;
-    this._savePromise = null;
-    this._saveThrowOnError = false;
-    this.lastSaveError = null;
+    this.saveQueue = Promise.resolve();
+    this._saveTimer = null;
+    this._saveRequested = false;
+    this._savePromise = null;
+    this._saveThrowOnError = false;
+    this.lastSaveError = null;
 
     
     this.annIndex = null;
@@ -303,8 +307,23 @@ export class EmbeddingsCache {
     
     this._clearedAfterIndex = false;
     this._loadPromise = null;
+    this._corruptionDetected = false;
   }
 
+  /**
+   * Returns true if the last load() detected binary store corruption.
+   * Used by the server to decide whether to trigger an automatic re-index.
+   */
+  shouldAutoReindex() {
+    return this._corruptionDetected === true;
+  }
+
+  consumeAutoReindex() {
+    const should = this._corruptionDetected === true;
+    this._corruptionDetected = false;
+    return should;
+  }
+
   
   addInitError(stage, error) {
     this.initErrors.push({
@@ -510,6 +529,7 @@ export class EmbeddingsCache {
 
   async load({ forceVectorLoadMode } = {}) {
     if (!this.config.enableCache) return;
+    this._corruptionDetected = false;
 
     try {
       await fs.mkdir(this.config.cacheDirectory, { recursive: true });
@@ -660,7 +680,19 @@ export class EmbeddingsCache {
           });
         } catch (err) {
           this.binaryStore = null;
-          console.warn(`[Cache] Failed to load binary vector store: ${err.message}`);
+          const isCorruption = err instanceof BinaryStoreCorruptionError ||
+            err?.name === 'BinaryStoreCorruptionError';
+          if (isCorruption) {
+            console.warn(`[Cache] Binary store corruption detected: ${err.message}`);
+            this._corruptionDetected = true;
+            await recordBinaryStoreCorruption(this.config.cacheDirectory, {
+              message: err.message,
+              context: 'cache.load binary store',
+              action: 'detected',
+            });
+          } else {
+            console.warn(`[Cache] Failed to load binary vector store: ${err.message}`);
+          }
         }
       }
 
@@ -773,39 +805,39 @@ export class EmbeddingsCache {
 
   
 
-  save({ throwOnError = false } = {}) {
-    if (!this.config.enableCache) return Promise.resolve();
-
-    this._saveRequested = true;
-    if (throwOnError) {
-      this._saveThrowOnError = true;
-    }
-
-    if (this._saveTimer) return this._savePromise ?? Promise.resolve();
+  save({ throwOnError = false } = {}) {
+    if (!this.config.enableCache) return Promise.resolve();
+
+    this._saveRequested = true;
+    if (throwOnError) {
+      this._saveThrowOnError = true;
+    }
+
+    if (this._saveTimer) return this._savePromise ?? Promise.resolve();
 
     const debounceMs = Number.isInteger(this.config.saveDebounceMs)
       ? this.config.saveDebounceMs
       : 250;
 
-    this._savePromise = new Promise((resolve, reject) => {
-      this._saveTimer = setTimeout(() => {
-        this._saveTimer = null;
-        const rejectOnSaveError = this._saveThrowOnError;
-        this._saveThrowOnError = false;
-
-        this.saveQueue = this.saveQueue
-          .catch(() => {
-            
-          })
-          .then(async () => {
-            while (this._saveRequested) {
-              this._saveRequested = false;
-              await this.performSave({ throwOnError: rejectOnSaveError });
-            }
-          })
-          .then(resolve, reject)
-          .finally(() => {
-            this._savePromise = null;
+    this._savePromise = new Promise((resolve, reject) => {
+      this._saveTimer = setTimeout(() => {
+        this._saveTimer = null;
+        const rejectOnSaveError = this._saveThrowOnError;
+        this._saveThrowOnError = false;
+
+        this.saveQueue = this.saveQueue
+          .catch(() => {
+            
+          })
+          .then(async () => {
+            while (this._saveRequested) {
+              this._saveRequested = false;
+              await this.performSave({ throwOnError: rejectOnSaveError });
+            }
+          })
+          .then(resolve, reject)
+          .finally(() => {
+            this._savePromise = null;
           });
       }, debounceMs);
     });
@@ -813,24 +845,24 @@ export class EmbeddingsCache {
     return this._savePromise;
   }
 
-  async performSave({ throwOnError = false } = {}) {
-    
-    this._saveInProgress = true;
-    if (
-      this.config.allowSystemWorkspaceCache !== true &&
-      this.config.searchDirectory &&
-      isNonProjectDirectory(this.config.searchDirectory)
-    ) {
-      const source = this.config.workspaceResolution?.source || 'unknown';
-      console.warn(
-        `[Cache] Skipping cache save for non-project workspace (${source}): ${this.config.searchDirectory}`
-      );
-      this._saveInProgress = false;
-      return;
-    }
-
-    
-    if (this.activeReads > 0) {
+  async performSave({ throwOnError = false } = {}) {
+    
+    this._saveInProgress = true;
+    if (
+      this.config.allowSystemWorkspaceCache !== true &&
+      this.config.searchDirectory &&
+      isNonProjectDirectory(this.config.searchDirectory)
+    ) {
+      const source = this.config.workspaceResolution?.source || 'unknown';
+      console.warn(
+        `[Cache] Skipping cache save for non-project workspace (${source}): ${this.config.searchDirectory}`
+      );
+      this._saveInProgress = false;
+      return;
+    }
+
+    
+    if (this.activeReads > 0) {
       const timeoutMs = this.config.saveReaderWaitTimeoutMs ?? DEFAULT_READER_WAIT_TIMEOUT_MS;
       const allReadersFinished = await this.waitForReadersWithTimeout(timeoutMs);
       if (!allReadersFinished && !this.config.forceSaveWithActiveReaders) {
@@ -998,9 +1030,9 @@ export class EmbeddingsCache {
 
       
       
-      if (
-        this.config.annIndexCache !== false &&
-        this.annPersistDirty &&
+      if (
+        this.config.annIndexCache !== false &&
+        this.annPersistDirty &&
         !this.annDirty &&
         !this._annWriting &&
         this.annIndex &&
@@ -1019,12 +1051,12 @@ export class EmbeddingsCache {
           console.warn(`[ANN] Failed to persist ANN index: ${error.message}`);
         } finally {
           this._annWriting = false;
-        }
-      }
-      this.lastSaveError = null;
-    } catch (error) {
-      this.lastSaveError = error instanceof Error ? error : new Error(String(error));
-      console.warn('[Cache] Failed to save cache:', this.lastSaveError.message);
+        }
+      }
+      this.lastSaveError = null;
+    } catch (error) {
+      this.lastSaveError = error instanceof Error ? error : new Error(String(error));
+      console.warn('[Cache] Failed to save cache:', this.lastSaveError.message);
       
       if (
         this.config.vectorStoreFormat === 'binary' &&
@@ -1043,9 +1075,9 @@ export class EmbeddingsCache {
         }
       }
       
-      if (
-        this.config.vectorStoreFormat === 'sqlite' &&
-        !this.sqliteStore
+      if (
+        this.config.vectorStoreFormat === 'sqlite' &&
+        !this.sqliteStore
       ) {
         try {
           console.info('[Cache] Attempting to recover SQLite store after failed save...');
@@ -1055,19 +1087,19 @@ export class EmbeddingsCache {
           }
         } catch (recoverErr) {
           console.warn(`[Cache] Failed to recover SQLite store: ${recoverErr.message}`);
-          this.sqliteStore = null;
-        }
-      }
-      if (throwOnError) {
-        const wrapped = new Error(`Cache save failed: ${this.lastSaveError.message}`);
-        wrapped.cause = this.lastSaveError;
-        throw wrapped;
-      }
-    } finally {
-      this.isSaving = false;
-      this._saveInProgress = false; 
-    }
-  }
+          this.sqliteStore = null;
+        }
+      }
+      if (throwOnError) {
+        const wrapped = new Error(`Cache save failed: ${this.lastSaveError.message}`);
+        wrapped.cause = this.lastSaveError;
+        throw wrapped;
+      }
+    } finally {
+      this.isSaving = false;
+      this._saveInProgress = false; 
+    }
+  }
 
   
 

package/lib/constants.js

@@ -248,8 +248,9 @@ export const EMBEDDING_PROCESS_GC_STATE_INITIAL = Object.freeze({
 /**
  * Binary vector store format version.
  * Increment when binary format changes to trigger re-indexing.
+ * v2: added writeId (4 bytes) + CRC32 (4 bytes) + 8 bytes reserved to all headers.
  */
-export const BINARY_STORE_VERSION = 1;
+export const BINARY_STORE_VERSION = 2;
 
 /**
  * SQLite vector store format version.
@@ -259,21 +260,21 @@ export const SQLITE_STORE_VERSION = 1;
 
 /**
  * Binary vector file header size in bytes.
- * Contains: magic (4) + version (4) + dim (4) + count (4) + reserved (4)
+ * Contains: magic (4) + version (4) + dim (4) + count (4) + writeId (4) + crc32 (4) + reserved (8)
  */
-export const BINARY_VECTOR_HEADER_SIZE = 20;
+export const BINARY_VECTOR_HEADER_SIZE = 32;
 
 /**
  * Binary record file header size in bytes.
- * Contains: magic (4) + version (4) + count (4) + reserved (8)
+ * Contains: magic (4) + version (4) + count (4) + fileCount (4) + writeId (4) + crc32 (4) + reserved (8)
  */
-export const BINARY_RECORD_HEADER_SIZE = 20;
+export const BINARY_RECORD_HEADER_SIZE = 32;
 
 /**
  * Binary content file header size in bytes.
- * Contains: magic (4) + version (4) + count (4) + reserved (8)
+ * Contains: magic (4) + version (4) + totalBytes (8) + writeId (4) + crc32 (4) + reserved (8)
  */
-export const BINARY_CONTENT_HEADER_SIZE = 20;
+export const BINARY_CONTENT_HEADER_SIZE = 32;
 
 /**
  * Size of a single record entry in bytes.