rag-memory-epf-mcp 6.3.1 → 6.4.0-rc.1

package/README.md

@@ -154,6 +154,50 @@ storeDocument(id, content, metadata)
 
 ## Changelog
 
+### v6.4.0 (2026-10-03)
+
+- (Release candidate `6.4.0-rc.1` on the `next` dist-tag; `latest` stays 6.3.2 until the published artifact passes a
+  canary against a real project database.)
+
+- **Changed** `hybridSearch` default ranking = reciprocal rank fusion of the vector and FTS5 candidate lists
+  (k=60). A chunk that only FTS5 finds — typically an exact identifier, filename or setting key — can now reach
+  the top; before, it scored at most 0.0164 and sat under every vector candidate in the measured corpora.
+  `relevance_score` on the default call is a rank score (at most 2/61, comparable only within one call). Measured on frozen snapshots: exact-identifier hit@10 7/20 → 18/20; worse on 0 of
+  203 queries across three corpora.
+- **Changed** the per-result summary path is opt-in (`RAG_MEMORY_SEARCH_SUMMARIES=on`). It embedded every
+  sentence fragment of every candidate (median 121 s per search) and its context boost pushed vector-0 chunks
+  to rank 1. `off` keeps working. Legacy paths (`summaries=on`, `useGraph: true`) keep the 6.3.2 formula.
+- **Changed** with the default model (bge-m3) queries are embedded as raw text: the bge-v1.5 instruction the loader
+  prepended to every query is gone (bge-m3 needs none; stored vectors never had it). A custom `EMBEDDING_MODEL` keeps
+  the previous query instruction. Paraphrase hit@10 7 → 9 of 20, identifier hit@1 7 → 8,
+  document known-item (`hybridSearch`) unchanged or +1; entity known-item (`searchNodes`) hit@10 unchanged,
+  hit@1 -1 / -1 / +1 (hub / uap / hal). No re-index.
+- Details and rollout: `docs/UPDATING.md`, `specs/changes/search-fusion-rrf/proposal.md`.
+
+### v6.3.2 (2026-09-25)
+
+- **Changed — on macOS the engine takes `-wal` and `-shm` out of cloud sync.** It sets
+  `com.apple.fileprovider.ignore#P = 1` on both files after every open (SQLite recreates them after the
+  last connection closes, so once is not enough). Measured with Google Drive for desktop: the client
+  treated `-wal` as a synced item and put a new file at the path while the engine held the old one open
+  (`lsof -p` showed the descriptor inside `FileProvider/…/wharf/delete/`); from then on every write
+  failed with `SQLITE_IOERR` ("disk I/O error") until the engine restarted — 10 s to 3 min after start,
+  with one engine attached. With the attribute set, the same live database kept the same `-wal` for
+  25 min of use. The main database file still syncs. Other platforms: no-op.
+- **Changed — a swapped sidecar is detected and the connection reopened.** The idle tick compares the
+  `-wal`/`-shm` inodes with the ones recorded at open (two consecutive mismatches) and reopens with the
+  same configuration; an `SQLITE_IOERR*` from a checkpoint or a tool call reopens too. A tool that hit
+  the I/O error is retried once only if repeating it changes nothing (reads, `createEntities`,
+  `createRelations`, `addObservations`, `deleteEntities`, `deleteRelations`); other tools get the
+  error back after the reopen. A reopen waits for running tool calls, is not done while shutting
+  down, and is braked after 3 in 10 s. A failed reopen retries with backoff and, after 10 failures,
+  shuts the server down so the host shows it as failed. A reconciliation cut by a reopen reruns.
+- Known limit: writes acknowledged in the last ~1 s before a swap can be lost if the old file is no
+  longer readable (the engine tries one checkpoint on the old handle first and logs `walsz-before=`).
+- The 6.3.1 `wal_checkpoint(TRUNCATE)` is unchanged. `RESTART` (± `journal_size_limit`) was measured and
+  rejected: after SIGKILL its WAL replayed onto a foreign main file 3/3 times.
+- No tool, argument, return shape or schema changed. Spec: `specs/changes/wal-sidecar-guard/`.
+
 ### v6.3.1
 
 - **Changed — the engine empties the WAL while it is idle.** It runs `wal_checkpoint(TRUNCATE)` itself:

package/dist/index.d.ts

@@ -3,6 +3,11 @@ import { type SourceInput } from './src/observations/lifecycle.js';
 import { EmbeddingGate } from './src/embeddingGate.js';
 import type { EmbedPriority } from './src/embeddingGate.js';
 import { BackfillCoordinator } from './src/backfillCoordinator.js';
+export declare const LEGACY_QUERY_INSTRUCTION = "Represent this sentence for searching relevant passages: ";
+export declare function embeddingInput(text: string, isQuery: boolean, defaultModel?: boolean): string;
+export declare function makeEmbedFn(model: (input: string, opts: any) => Promise<{
+    data: any;
+}>, defaultModel: boolean): (text: string, dims: number, isQuery: boolean) => Promise<Float32Array<ArrayBuffer>>;
 export declare function compileFtsLiteralQuery(q: string): string | null;
 export declare function resolveDbFilePath(envValue: string | undefined, cwd: string, serverDir: string): string;
 export declare function parseMmapSize(raw: string | undefined): number;
@@ -51,6 +56,7 @@ interface DetailedContext {
 export declare class SyncCasConflictError extends Error {
     constructor(documentId: string);
 }
+export declare function isIoError(e: unknown): boolean;
 export declare function setSyncFaultPoint(point: string | null, fn: (() => void) | null): void;
 export interface ReuseCandidate {
     rowid: number;
@@ -82,6 +88,7 @@ export declare class RAGKnowledgeGraphManager {
         gate?: EmbeddingGate;
         __testForceFkOff?: boolean;
     }): Promise<void>;
+    private openConnection;
     private ensureCurrentProfile;
     private buildRealLoader;
     startReconciliation(): Promise<void>;
@@ -102,6 +109,26 @@ export declare class RAGKnowledgeGraphManager {
         }>;
     }>;
     checkpointWal(): boolean;
+    walIno: bigint | null;
+    shmIno: bigint | null;
+    reopenCount: number;
+    private reopenTimes;
+    private inFlight;
+    private pendingReopen;
+    private walMismatchTicks;
+    private walWatchPausedUntil;
+    private walWatchOff;
+    private lastWalSize;
+    private dbDown;
+    shuttingDown: boolean;
+    onFatal: (() => void) | null;
+    guardSidecars(): void;
+    walTick(): boolean;
+    private stormCount;
+    reopenDb(reason: string, force?: boolean): boolean;
+    private openAfterClose;
+    private retryOpen;
+    runWithIoRecovery<T>(tool: string, fn: () => Promise<T>): Promise<T>;
     private walTimer;
     private walSoon;
     startWalKeeper(tickMs?: number): void;

package/dist/index.js

@@ -6,6 +6,7 @@ import Database from 'better-sqlite3';
 import * as sqliteVec from 'sqlite-vec';
 import { get_encoding } from 'tiktoken';
 import fsSync from 'fs';
+import { execFileSync } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { pipeline, env } from '@huggingface/transformers';
@@ -66,6 +67,24 @@ function printBanner(opts) {
 // operators (every term is double-quoted; special characters stripped exactly
 // as the pre-3.6 hybridSearch sanitizer did). Returns null when nothing
 // searchable remains (contract: caller returns empty results + warning).
+// search-fusion-rrf (query input): what the model sees for a text. For the DEFAULT model (bge-m3) queries are
+// embedded as raw text — the model card: "the BGE-M3 model no longer requires adding instructions to the
+// queries"; measured on the frozen hub snapshot (93 queries, full-corpus vector rank): 36 better, 6 worse, 51 same.
+// A CUSTOM model (EMBEDDING_MODEL set to something else) keeps the pre-change query instruction: the evidence
+// above is for bge-m3 only, and some models (e.g. bge v1.5) still recommend an instruction on queries.
+// Passages are always raw. `isQuery` stays in the signature and in the embedding cache key.
+export const LEGACY_QUERY_INSTRUCTION = 'Represent this sentence for searching relevant passages: ';
+export function embeddingInput(text, isQuery, defaultModel = true) {
+    return isQuery && !defaultModel ? `${LEGACY_QUERY_INSTRUCTION}${text}` : text;
+}
+// The embed function handed to the gate. Exported so the input wiring is testable with a stub model.
+export function makeEmbedFn(model, defaultModel) {
+    return async (text, dims, isQuery) => {
+        const input = embeddingInput(text, isQuery, defaultModel);
+        const r = await model(input, { pooling: 'cls', normalize: true });
+        return new Float32Array(r.data.slice(0, dims));
+    };
+}
 export function compileFtsLiteralQuery(q) {
     const sanitized = q.replace(/["\*\(\)\-]/g, ' ').trim();
     if (!sanitized)
@@ -136,6 +155,30 @@ const TEXT_BUILDER_VERSION = 'tb1';
 export class SyncCasConflictError extends Error {
     constructor(documentId) { super(`sync CAS conflict on ${documentId}`); this.name = 'SyncCasConflictError'; }
 }
+// Sidecar guard (specs/changes/wal-sidecar-guard). macOS File Provider attribute that takes an
+// item out of sync; Google Drive for desktop honours it (measured: isExcludedFromSync = 1).
+const SYNC_EXCLUDE_ATTR = 'com.apple.fileprovider.ignore#P';
+const REOPEN_STORM_WINDOW_MS = 10_000;
+const REOPEN_STORM_MAX = 3;
+const REOPEN_MAX_TRIES = 10;
+const WAL_WATCH_PAUSE_MS = 60_000;
+// Tools that may be retried once after an I/O error reopened the connection: reads, and writes
+// whose repetition changes nothing (INSERT OR IGNORE / content dedup / deletes). Everything else
+// gets the error back so the caller decides — e.g. syncDocumentFromFile spans several
+// transactions and its repeat-safety is not proven.
+const IDEMPOTENT_TOOLS = new Set([
+    'readGraph', 'searchNodes', 'openNodes', 'getNeighbors', 'hybridSearch', 'getDetailedContext',
+    'getKnowledgeGraphStats', 'listDocuments', 'exportGraph', 'getMigrationStatus', 'getGraphMetrics',
+    'detectCommunities', 'analyzeGraphStructure', 'getObservationHistory',
+    'createEntities', 'createRelations', 'addObservations',
+    // deleteObservations / deleteDocuments are left out on purpose: a retry after a committed
+    // delete reports 0 deleted, which a caller reads as "nothing was deleted".
+    'deleteEntities', 'deleteRelations',
+]);
+export function isIoError(e) {
+    const code = e?.code;
+    return typeof code === 'string' && code.startsWith('SQLITE_IOERR');
+}
 // Test-only fault hook (v13 setMigrationFaultPoint 선례 — 환경변수 금지: 상시 스위치는
 // 오설정 한 줄로 sync 를 깬다).
 let __syncFaultHook = null;
@@ -219,38 +262,7 @@ export class RAGKnowledgeGraphManager {
     // 호출부에서 읽히게 하기 위해서다.
     async initialize(opts = {}) {
         console.error('🚀 Initializing RAG Knowledge Graph MCP Server...');
-        this.db = new Database(DB_FILE_PATH);
-        sqliteVec.load(this.db);
-        this.db.pragma('journal_mode = WAL');
-        this.db.pragma('synchronous = NORMAL');
-        this.db.pragma('busy_timeout = 5000');
-        this.db.pragma('cache_size = -32000');
-        this.db.pragma('temp_store = MEMORY');
-        // Opt-in mmap (see MMAP_SIZE above). Read the applied value back so the banner reports
-        // what SQLite did, not what we asked for (a compile-time cap can lower it silently).
-        this.db.pragma(`mmap_size = ${MMAP_SIZE}`);
-        this.mmapApplied = Number(this.db.pragma('mmap_size', { simple: true }));
-        this.db.pragma('foreign_keys = ON');
-        // spec §5.2: 관찰 lifecycle 의 무결성은 전부 FK CASCADE 를 전제한다 — root 를 지우면
-        // revision 이, revision 을 지우면 source 가 따라가야 history 가 고아로 남지 않는다.
-        // FK 가 꺼진 채 돌면 그 계약이 조용히 무효가 되고, 그게 최악이다. 스키마를 건드리기
-        // 전에(= runMigrations 앞에서) 멈춘다.
-        // 트랜잭션 내부에서는 이 pragma 가 no-op 이므로(실측 before=1·during=1·after=1)
-        // 부팅 시점 확인이 유일한 방어 지점이다.
-        //
-        // 음성 대조군 주입은 **인자로만** 받는다. 환경변수로 두면 프로덕션 경로에
-        // "부팅을 막는 스위치"가 상시 존재하게 되고, 오설정 한 줄로 서버가 안 뜬다
-        // (advisor beta 자기의심 2 = "더 나쁘다"). 테스트는 manager 를 직접 만들므로
-        // 인자 주입으로 충분하다.
-        if (opts.__testForceFkOff)
-            this.db.pragma('foreign_keys = OFF');
-        {
-            const fk = this.db.pragma('foreign_keys', { simple: true });
-            if (Number(fk) !== 1) {
-                throw new Error(`foreign_keys is ${fk}, expected 1. The observation lifecycle relies on FK CASCADE ` +
-                    `for history integrity; refusing to run migrations without it.`);
-            }
-        }
+        this.openConnection(opts.__testForceFkOff === true);
         this.encoding = get_encoding("cl100k_base");
         await this.runMigrations();
         this.currentProfileId = this.ensureCurrentProfile();
@@ -259,6 +271,8 @@ export class RAGKnowledgeGraphManager {
         this.db.prepare(`INSERT INTO server_meta (key, value) VALUES ('current_default_chunker', ?)
                      ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
             .run(effectiveSignature(DEFAULT_MAX_TOKENS));
+        // The writes above created the sidecars; mark them before a sync client can take them.
+        this.guardSidecars();
         this.embeddingsMode = opts.skipModel
             ? 'off'
             : (process.env.RAG_MEMORY_EMBEDDINGS || 'lazy');
@@ -287,6 +301,42 @@ export class RAGKnowledgeGraphManager {
         const systemInfo = getSystemInfo();
         console.error(`📊 System Info: ${systemInfo.toolCounts.total} tools available (${systemInfo.toolCounts.knowledgeGraph} knowledge graph, ${systemInfo.toolCounts.rag} RAG, ${systemInfo.toolCounts.graphQuery} query)`);
     }
+    // Opens the connection and applies everything the engine attaches to it. Shared by
+    // initialize() and reopenDb() so a reopened connection is configured exactly like the first.
+    openConnection(forceFkOff = false) {
+        this.db = new Database(DB_FILE_PATH);
+        sqliteVec.load(this.db);
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('synchronous = NORMAL');
+        this.db.pragma('busy_timeout = 5000');
+        this.db.pragma('cache_size = -32000');
+        this.db.pragma('temp_store = MEMORY');
+        // Opt-in mmap (see MMAP_SIZE above). Read the applied value back so the banner reports
+        // what SQLite did, not what we asked for (a compile-time cap can lower it silently).
+        this.db.pragma(`mmap_size = ${MMAP_SIZE}`);
+        this.mmapApplied = Number(this.db.pragma('mmap_size', { simple: true }));
+        this.db.pragma('foreign_keys = ON');
+        // spec §5.2: 관찰 lifecycle 의 무결성은 전부 FK CASCADE 를 전제한다 — root 를 지우면
+        // revision 이, revision 을 지우면 source 가 따라가야 history 가 고아로 남지 않는다.
+        // FK 가 꺼진 채 돌면 그 계약이 조용히 무효가 되고, 그게 최악이다. 스키마를 건드리기
+        // 전에(= runMigrations 앞에서) 멈춘다.
+        // 트랜잭션 내부에서는 이 pragma 가 no-op 이므로(실측 before=1·during=1·after=1)
+        // 부팅 시점 확인이 유일한 방어 지점이다.
+        //
+        // 음성 대조군 주입은 **인자로만** 받는다. 환경변수로 두면 프로덕션 경로에
+        // "부팅을 막는 스위치"가 상시 존재하게 되고, 오설정 한 줄로 서버가 안 뜬다
+        // (advisor beta 자기의심 2 = "더 나쁘다"). 테스트는 manager 를 직접 만들므로
+        // 인자 주입으로 충분하다.
+        if (forceFkOff)
+            this.db.pragma('foreign_keys = OFF');
+        {
+            const fk = this.db.pragma('foreign_keys', { simple: true });
+            if (Number(fk) !== 1) {
+                throw new Error(`foreign_keys is ${fk}, expected 1. The observation lifecycle relies on FK CASCADE ` +
+                    `for history integrity; refusing to run migrations without it.`);
+            }
+        }
+    }
     // Upsert the stored-vector compatibility profile (spec §6c layer 2) and record
     // retrieval config in server_meta (layer 3 — never a backfill trigger).
     ensureCurrentProfile() {
@@ -303,8 +353,12 @@ export class RAGKnowledgeGraphManager {
             .get(EMBEDDING_MODEL, MODEL_REVISION, MODEL_DTYPE, dims, 'cls', 1);
         this.db.prepare(`INSERT INTO server_meta(key,value) VALUES('current_profile_id',?)
       ON CONFLICT(key) DO UPDATE SET value=excluded.value`).run(String(row.id));
-        this.db.prepare(`INSERT INTO server_meta(key,value) VALUES('query_prefix_version','1')
-      ON CONFLICT(key) DO NOTHING`).run();
+        // query_prefix_version: diagnostic marker of the query-input convention of the engine that last INITIALISED
+        // this DB — 1 = instruction prepended to queries (<= 6.3.2, and custom models now), 2 = raw queries (default
+        // bge-m3 since search-fusion-rrf). It is written at init, not per query: it does not prove what the last query
+        // used, which engines are attached, or vector compatibility. Nothing reads it for logic.
+        this.db.prepare(`INSERT INTO server_meta(key,value) VALUES('query_prefix_version',?)
+      ON CONFLICT(key) DO UPDATE SET value=excluded.value`).run(IS_DEFAULT_MODEL_CONFIG ? '2' : '1');
         return row.id;
     }
     // Real model loader used by the gate: version-independent cache dir with a
@@ -342,11 +396,7 @@ export class RAGKnowledgeGraphManager {
             if (role === 'owner')
                 lock.markComplete();
             console.error(`✅ ${EMBEDDING_MODEL} model loaded (${MODEL_DTYPE})`);
-            return async (text, dims, isQuery) => {
-                const input = isQuery ? `Represent this sentence for searching relevant passages: ${text}` : text;
-                const r = await model(input, { pooling: 'cls', normalize: true });
-                return new Float32Array(r.data.slice(0, dims));
-            };
+            return makeEmbedFn(model, IS_DEFAULT_MODEL_CONFIG);
         }
         catch (e) {
             // Cache policy by CAUSE and ROLE (beta 2R B3 -> 4R M1 -> 5R M1), unit-
@@ -544,6 +594,7 @@ export class RAGKnowledgeGraphManager {
     // session construction at exit — risks an ugly abort message, never data
     // loss. Hanging forever is the alternative and is worse.
     async shutdownAll() {
+        this.shuttingDown = true;
         console.error('\n🧹 Cleaning up...');
         try {
             await this.coordinator?.shutdown(5000);
@@ -626,10 +677,206 @@ export class RAGKnowledgeGraphManager {
                 this.db.pragma('busy_timeout = 5000');
             }
         }
-        catch {
+        catch (e) {
+            // An I/O error here means the connection is pointing at a file that is no longer the one
+            // at the path (see guardSidecars). Retrying on the same connection cannot succeed.
+            if (isIoError(e))
+                this.reopenDb(`checkpoint-${e.code}`, true);
             return false; // inside a transaction, or the file is locked — the next tick retries
         }
     }
+    // --- Sidecar guard (specs/changes/wal-sidecar-guard) -------------------------------------
+    // Measured 2026-09-25 (macOS + Google Drive): the sync client treated `-wal` as a synced item
+    // and swapped a new file in at the path while the engine held the old one open; every write
+    // then failed with SQLITE_IOERR until restart. Excluding the sidecars from sync takes them out
+    // of the client's hands, and it matches the WAL-exit contract: a WAL that never leaves this
+    // machine cannot be replayed onto another machine's main file. The attribute lives on the
+    // inode and SQLite recreates both files after the last connection closes, so it is set after
+    // every open and whenever a sidecar at the path is not the one recorded here.
+    walIno = null;
+    shmIno = null;
+    reopenCount = 0;
+    reopenTimes = [];
+    inFlight = 0; // tool calls running (reopen waits for them)
+    pendingReopen = null;
+    walMismatchTicks = 0; // a swap must be seen on 2 consecutive ticks
+    walWatchPausedUntil = 0; // storm brake for the inode watch
+    walWatchOff = false; // file system gives no inode (ino 0)
+    lastWalSize = 0;
+    dbDown = null;
+    shuttingDown = false;
+    // Set by main(): the full shutdown (closes the MCP transport first, then the engine). Without it
+    // the process would stay alive on stdin with no database.
+    onFatal = null;
+    guardSidecars() {
+        const wal = DB_FILE_PATH + '-wal', shm = DB_FILE_PATH + '-shm';
+        if (process.platform === 'darwin') {
+            for (const p of [wal, shm]) {
+                if (!fsSync.existsSync(p))
+                    continue;
+                try {
+                    execFileSync('/usr/bin/xattr', ['-w', SYNC_EXCLUDE_ATTR, '1', p], { stdio: 'ignore' });
+                }
+                catch (e) {
+                    // Fail open: the attribute is protection, not a correctness condition.
+                    console.error(`⚠️ sidecar sync-exclude failed: ${p}: ${e.message}`);
+                }
+            }
+        }
+        const w = fsSync.statSync(wal, { throwIfNoEntry: false, bigint: true });
+        const h = fsSync.statSync(shm, { throwIfNoEntry: false, bigint: true });
+        this.walIno = w ? w.ino : null;
+        this.shmIno = h ? h.ino : null;
+        if (w && w.ino === 0n && !this.walWatchOff) {
+            this.walWatchOff = true;
+            console.error('⚠️ file system reports inode 0 — sidecar swap watch disabled');
+        }
+        this.walMismatchTicks = 0;
+    }
+    // Runs on the WAL keeper tick. Returns true when it reopened.
+    walTick() {
+        if (this.shuttingDown)
+            return false;
+        if (!this.db)
+            return this.dbDown ? this.retryOpen() : false;
+        if (this.walWatchOff || Date.now() < this.walWatchPausedUntil)
+            return false;
+        const w = fsSync.statSync(DB_FILE_PATH + '-wal', { throwIfNoEntry: false, bigint: true });
+        const h = fsSync.statSync(DB_FILE_PATH + '-shm', { throwIfNoEntry: false, bigint: true });
+        if (this.walIno === null) {
+            // Nothing recorded yet (no write had created the file): record and mark it now.
+            if (w)
+                this.guardSidecars();
+            return false;
+        }
+        const walOk = !!w && w.ino === this.walIno;
+        const shmOk = this.shmIno === null || (!!h && h.ino === this.shmIno);
+        if (walOk && shmOk) {
+            this.walMismatchTicks = 0;
+            if (w)
+                this.lastWalSize = Number(w.size);
+            return false;
+        }
+        // Two consecutive ticks, so a value that flickers back within a second is not a swap.
+        if (++this.walMismatchTicks < 2)
+            return false;
+        const reason = !w ? 'wal-missing' : !walOk ? 'wal-inode-changed' : 'shm-inode-changed';
+        if (this.inFlight > 0) {
+            this.pendingReopen = reason;
+            return false;
+        }
+        return this.reopenDb(reason);
+    }
+    stormCount() {
+        const now = Date.now();
+        return this.reopenTimes.filter(t => now - t < REOPEN_STORM_WINDOW_MS).length;
+    }
+    // Close and reopen the connection with the same configuration. Migrations are not rerun.
+    // Returns false when there was nothing to reopen or the reopen failed (the engine then
+    // retries with backoff from the keeper tick and, after REOPEN_MAX_TRIES, exits so the host
+    // sees a failed server instead of a live one that answers every call with an error).
+    // force = an I/O error was seen on this handle: reopen even inside the storm window (holding a
+    // dead handle helps nobody). The storm brake is for the inode watch.
+    reopenDb(reason, force = false) {
+        if (this.shuttingDown || !this.db)
+            return false;
+        if (!force && this.stormCount() >= REOPEN_STORM_MAX) {
+            // Keep the connection; pause the inode watch so a flickering file system cannot make
+            // this a once-a-second close/open loop. An IOERR path still gets its error.
+            this.walWatchPausedUntil = Date.now() + WAL_WATCH_PAUSE_MS;
+            console.error(`⚠️ reopen storm (${REOPEN_STORM_MAX} in ${REOPEN_STORM_WINDOW_MS / 1000}s) — watch paused, reason=${reason}`);
+            return false;
+        }
+        const old = this.db;
+        // Salvage: frames committed to the old WAL after the last checkpoint (≤1 s) go to the main
+        // file if the old descriptor is still readable. An I/O error here just means they are gone.
+        // busy_timeout 0: another engine's read snapshot must not stall this for 5 s.
+        try {
+            old.pragma('busy_timeout = 0');
+            old.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        catch { /* old file unreadable */ }
+        try {
+            old.close();
+        }
+        catch { /* the handle may already be unusable */ }
+        this.db = null;
+        this.reopenTimes.push(Date.now());
+        return this.openAfterClose(reason);
+    }
+    openAfterClose(reason) {
+        try {
+            this.openConnection();
+            this.guardSidecars();
+        }
+        catch (e) {
+            try {
+                this.db?.close();
+            }
+            catch { /* half-open */ }
+            this.db = null;
+            const tries = (this.dbDown?.tries ?? 0) + 1;
+            const delay = Math.min(1000 * 2 ** (tries - 1), 60_000);
+            this.dbDown = { reason, tries, nextAt: Date.now() + delay };
+            console.error(`❌ db reopen failed (reason=${reason}, try=${tries}): ${e.message}`);
+            if (tries >= REOPEN_MAX_TRIES) {
+                console.error('❌ database cannot be reopened — exiting so the host shows a failed server');
+                process.exitCode = 1;
+                if (this.onFatal)
+                    this.onFatal();
+                else
+                    void this.shutdownAll().finally(() => process.exit(process.exitCode ?? 1));
+            }
+            return false;
+        }
+        this.dbDown = null;
+        this.pendingReopen = null;
+        this.reopenCount++;
+        console.error(`🔁 db reopened (reason=${reason}, n=${this.reopenCount}, walsz-before=${this.lastWalSize})`);
+        // A reconciliation cut short by the old handle is 'pending', not failed — run it again.
+        if (this.coordinator?.reconState === 'pending')
+            void this.startReconciliation().catch(() => { });
+        return true;
+    }
+    retryOpen() {
+        if (this.shuttingDown)
+            return false;
+        if (!this.dbDown || Date.now() < this.dbDown.nextAt)
+            return false;
+        return this.openAfterClose(`retry-${this.dbDown.reason}`);
+    }
+    // Tool-call wrapper: an SQLITE_IOERR* reopens the connection. The call is retried once only
+    // when the tool is idempotent — a failed transaction is rolled back whole, but a tool can
+    // span several transactions, so a non-idempotent one gets the error back (after the reopen)
+    // and the caller decides. Too many reopens in a short window → no retry, surface the error.
+    async runWithIoRecovery(tool, fn) {
+        if (!this.db && this.dbDown)
+            this.retryOpen();
+        const handle = this.db;
+        this.inFlight++;
+        try {
+            try {
+                return await fn();
+            }
+            catch (e) {
+                if (!isIoError(e))
+                    throw e;
+                const storm = this.stormCount() >= REOPEN_STORM_MAX;
+                // Several calls hit by one swap reopen once: if another call already replaced the
+                // handle, just use the new one.
+                const reopened = (this.db !== null && this.db !== handle)
+                    || this.reopenDb(`tool-${tool}-${e.code}`, true);
+                if (storm || !reopened || !IDEMPOTENT_TOOLS.has(tool))
+                    throw e;
+                return await fn();
+            }
+        }
+        finally {
+            this.inFlight--;
+            if (this.inFlight === 0 && this.pendingReopen)
+                this.reopenDb(this.pendingReopen);
+        }
+    }
     walTimer = null;
     walSoon = null;
     // Every write path ends up here without having to be listed: the periodic tick looks at
@@ -638,7 +885,15 @@ export class RAGKnowledgeGraphManager {
     startWalKeeper(tickMs = 1000) {
         if (this.walTimer)
             return;
-        this.walTimer = setInterval(() => { this.checkpointWal(); }, tickMs);
+        this.walTimer = setInterval(() => {
+            try {
+                this.walTick();
+            }
+            catch (e) {
+                console.error(`⚠️ wal tick: ${e.message}`);
+            }
+            this.checkpointWal();
+        }, tickMs);
         this.walTimer.unref();
     }
     noteActivity(delayMs = 200) {
@@ -648,6 +903,7 @@ export class RAGKnowledgeGraphManager {
         this.walSoon.unref();
     }
     cleanup() {
+        this.shuttingDown = true;
         if (this.walTimer) {
             clearInterval(this.walTimer);
             this.walTimer = null;
@@ -3311,6 +3567,9 @@ export class RAGKnowledgeGraphManager {
             throw new Error('Database not initialized');
         if (!this.encoding)
             throw new Error('Tokenizer not initialized');
+        // search-fusion-rrf: summary mode is read ONCE, at call entry (before any await), and used for the
+        // whole call. Opt-in since this change (was opt-out via =off in v5..6.3.2).
+        const summariesOn = process.env.RAG_MEMORY_SEARCH_SUMMARIES === 'on';
         console.error(`🔍 Enhanced hybrid search: "${query}"`);
         // Parity with searchNodes (beta 1R supplement): an unsearchable query gets
         // an explicit warning instead of a silent empty envelope.
@@ -3374,6 +3633,11 @@ export class RAGKnowledgeGraphManager {
             }
             catch (embErr) {
                 vectorDegraded = true;
+                // search-fusion-rrf (D5): a failure on a LATER cross-lingual variant used to leave the earlier
+                // variants' vector candidates in resultMap while the envelope said 'fts-only'. Drop them so the
+                // degraded call really is FTS-only (no vector rank, no summary, no graph) in every mode.
+                resultMap.clear();
+                primaryQueryEmbedding = null;
                 // 'inference_error' (not 'model_not_ready'): model_state may still read
                 // 'ready' here — a contradictory reason pair confused callers (beta B6).
                 degradationReason = this.degradationReason() ?? 'inference_error';
@@ -3381,6 +3645,12 @@ export class RAGKnowledgeGraphManager {
             }
         }
         const vectorResults = Array.from(resultMap.values()).sort((a, b) => a.distance - b.distance);
+        // search-fusion-rrf: vector rank (1-based, best distance across variants) for rank fusion.
+        // Taken here, before FTS5-only candidates are appended to vectorResults below.
+        const vectorRankOf = new Map(vectorResults.map((r, i) => [r.chunk_id, i + 1]));
+        // Default ranking = reciprocal rank fusion of the vector list and the FTS5 list (k=60).
+        // The legacy formula stays for the opt-in diagnostics (summaries on, graph re-ranker on).
+        const rankFusion = !useGraph && !summariesOn;
         // FTS5 full-text search as additional signal (Reciprocal Rank Fusion)
         const ftsBoostMap = new Map();
         try {
@@ -3569,12 +3839,12 @@ export class RAGKnowledgeGraphManager {
                 graphBoost += Math.min(entityBoost, 0.4);
             }
             // Generate semantic summary (skip when degraded — no embeddings available).
-            // RAG_MEMORY_SEARCH_SUMMARIES=off: diagnostic escape hatch (v5) — the summary
-            // path embeds EVERY sentence of EVERY candidate (~100+ inferences per search,
-            // measured 90-120s cold). Off = preview slices + relevanceScore 0; ranking
-            // then rests on vectorSimilarity + boosts. Default unchanged.
+            // search-fusion-rrf: the summary path is OPT-IN (RAG_MEMORY_SEARCH_SUMMARIES=on). It embeds
+            // every sentence fragment of every candidate one at a time (~400 inferences per search on a
+            // real corpus, median 121 s measured 2026-10-03) and its unbounded context boost let
+            // vector-0 chunks take rank 1 (known-item hit@1 9/10 off vs 4/10 on). Default = preview slices.
             let summary, keyHighlight, relevanceScore;
-            if (vectorDegraded || !primaryQueryEmbedding || process.env.RAG_MEMORY_SEARCH_SUMMARIES === 'off') {
+            if (vectorDegraded || !primaryQueryEmbedding || !summariesOn) {
                 keyHighlight = result.text.slice(0, 150);
                 summary = result.text.slice(0, 300);
                 relevanceScore = 0;
@@ -3584,8 +3854,11 @@ export class RAGKnowledgeGraphManager {
                 ));
             }
             const vectorSimilarity = Math.max(0, 1 - result.distance / 2);
-            const ftsBoost = ftsBoostMap.get(result.chunk_id) || 0;
-            const finalScore = Math.max(vectorSimilarity, relevanceScore) + graphBoost + ftsBoost;
+            const ftsBoost = ftsBoostMap.get(result.chunk_id) || 0; // = 1/(60 + FTS rank), 0 if not an FTS hit
+            const vectorRank = vectorRankOf.get(result.chunk_id);
+            const finalScore = rankFusion
+                ? (vectorRank !== undefined ? 1 / (60 + vectorRank) : 0) + ftsBoost
+                : Math.max(vectorSimilarity, relevanceScore) + graphBoost + ftsBoost;
             // Determine document title and source ID
             let documentTitle;
             let sourceId;
@@ -4127,116 +4400,119 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         // Validate arguments using our structured schema
         const validatedArgs = validateToolArgs(name, args);
         ragKgManager.noteActivity(); // fold the WAL shortly after this call, whatever it wrote
-        switch (name) {
-            // Original MCP tools
-            case "createEntities":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.createEntities(validatedArgs.entities), null, 2) }] };
-            case "createRelations":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.createRelations(validatedArgs.relations), null, 2) }] };
-            case "addObservations":
-                // v13: status·sources 를 그대로 넘긴다. 여기서 떨어뜨리면 스키마가 받아도
-                // 엔진에 도달하지 않아 provenance 가 조용히 사라진다.
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.addObservations(validatedArgs.observations), null, 2) }] };
-            // v13 observation lifecycle (spec §6.1 / §6.2)
-            case "correctObservation":
-                return { content: [{ type: "text", text: JSON.stringify({ observation_id: await ragKgManager.correctObservation(validatedArgs.observation_id, validatedArgs.content, validatedArgs.change_kind ?? 'correction', validatedArgs.reason) }, null, 2) }] };
-            case "retractObservation":
-                await ragKgManager.retractObservation(validatedArgs.observation_id, validatedArgs.reason);
-                return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'retracted' }, null, 2) }] };
-            case "restoreObservation":
-                await ragKgManager.restoreObservation(validatedArgs.observation_id, validatedArgs.reason);
-                return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'active' }, null, 2) }] };
-            case "approveObservation":
-                await ragKgManager.approveObservation(validatedArgs.observation_id, validatedArgs.reason);
-                return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'active' }, null, 2) }] };
-            case "declineObservation":
-                await ragKgManager.declineObservation(validatedArgs.observation_id, validatedArgs.reason);
-                return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'retracted' }, null, 2) }] };
-            case "purgeObservation":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.purgeObservation(validatedArgs.observation_id, validatedArgs.confirm), null, 2) }] };
-            case "getObservationHistory":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getObservationHistory({
-                                entity_name: validatedArgs.entity_name,
-                                observation_id: validatedArgs.observation_id,
-                                root_id: validatedArgs.root_id,
-                            }), null, 2) }] };
-            case "deleteEntities":
-                await ragKgManager.deleteEntities(validatedArgs.entityNames);
-                return { content: [{ type: "text", text: "Entities deleted successfully" }] };
-            case "deleteObservations":
-                // v3.6 (spec §5c, breaking): structured per-entity results replace the
-                // bare success string — mixed embedded/queued/no-op states are visible.
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.deleteObservations(validatedArgs.deletions), null, 2) }] };
-            case "deleteRelations":
-                await ragKgManager.deleteRelations(validatedArgs.relations);
-                return { content: [{ type: "text", text: "Relations deleted successfully" }] };
-            case "updateRelations":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.updateRelations(validatedArgs.updates), null, 2) }] };
-            case "readGraph":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.readGraph(), null, 2) }] };
-            case "searchNodes":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.searchNodes(validatedArgs.query, validatedArgs.limit || 10, validatedArgs.since, validatedArgs.until), null, 2) }] };
-            case "openNodes":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.openNodes(validatedArgs.names), null, 2) }] };
-            case "getNeighbors":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getNeighbors(validatedArgs.entityNames, validatedArgs.depth || 1, validatedArgs.relationType), null, 2) }] };
-            // New RAG tools
-            case "storeDocument":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.storeDocument(validatedArgs.id, validatedArgs.content, validatedArgs.metadata || {}), null, 2) }] };
-            case "chunkDocument":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.chunkDocument(validatedArgs.documentId, { maxTokens: validatedArgs.maxTokens, overlap: validatedArgs.overlap }), null, 2) }] };
-            case "embedChunks":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.embedChunks(validatedArgs.documentId), null, 2) }] };
-            case "extractTerms":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.extractTerms(validatedArgs.documentId, { minLength: validatedArgs.minLength, includeCapitalized: validatedArgs.includeCapitalized, customPatterns: validatedArgs.customPatterns }), null, 2) }] };
-            case "linkEntitiesToDocument":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.linkEntitiesToDocument(validatedArgs.documentId, validatedArgs.entityNames), null, 2) }] };
-            case "hybridSearch":
-                const limit = typeof validatedArgs.limit === 'number' ? validatedArgs.limit : 5;
-                // v5.3.0: graph is opt-in — only an explicit true enables the re-ranker (schema default false).
-                const useGraph = validatedArgs.useGraph === true;
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.hybridSearch(validatedArgs.query, limit, useGraph), null, 2) }] };
-            case "getDetailedContext":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getDetailedContext(validatedArgs.chunkId, validatedArgs.includeSurrounding !== false), null, 2) }] };
-            case "getKnowledgeGraphStats":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getKnowledgeGraphStats(), null, 2) }] };
-            case "deleteDocuments":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.deleteDocuments(validatedArgs.documentIds), null, 2) }] };
-            case "listDocuments":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.listDocuments(validatedArgs.includeMetadata !== false), null, 2) }] };
-            case "syncDocumentFromFile":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.syncDocumentFromFile(validatedArgs.path, validatedArgs.documentId, {
-                                metadata: validatedArgs.metadata,
-                                content: validatedArgs.content,
-                                excludePattern: validatedArgs.excludePattern,
-                                entityNames: validatedArgs.entityNames,
-                                chunkParams: validatedArgs.chunkParams,
-                            }), null, 2) }] };
-            // NEW: Entity embedding tools
-            case "embedAllEntities":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.embedAllEntities(), null, 2) }] };
-            // NEW: Export/Import tools
-            case "exportGraph":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.exportGraph(), null, 2) }] };
-            case "importGraph":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.importGraph(validatedArgs.data, { merge: validatedArgs.merge !== false }), null, 2) }] };
-            // NEW: Migration tools
-            case "getMigrationStatus":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getMigrationStatus(), null, 2) }] };
-            case "runMigrations":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.runMigrations(), null, 2) }] };
-            case "rollbackMigration":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.rollbackMigration(validatedArgs.targetVersion), null, 2) }] };
-            // Graph Analytics tools (graphology)
-            case "getGraphMetrics":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getGraphMetrics(validatedArgs.entityNames, validatedArgs.metrics, validatedArgs.limit || 10), null, 2) }] };
-            case "detectCommunities":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.detectCommunities(validatedArgs.resolution || 1.0), null, 2) }] };
-            case "analyzeGraphStructure":
-                return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.analyzeGraphStructure(), null, 2) }] };
-            default:
-                throw new Error(`Unknown tool: ${name}`);
-        }
+        // An SQLITE_IOERR* reopens the connection; idempotent tools are retried once (wal-sidecar-guard).
+        return await ragKgManager.runWithIoRecovery(name, async () => {
+            switch (name) {
+                // Original MCP tools
+                case "createEntities":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.createEntities(validatedArgs.entities), null, 2) }] };
+                case "createRelations":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.createRelations(validatedArgs.relations), null, 2) }] };
+                case "addObservations":
+                    // v13: status·sources 를 그대로 넘긴다. 여기서 떨어뜨리면 스키마가 받아도
+                    // 엔진에 도달하지 않아 provenance 가 조용히 사라진다.
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.addObservations(validatedArgs.observations), null, 2) }] };
+                // v13 observation lifecycle (spec §6.1 / §6.2)
+                case "correctObservation":
+                    return { content: [{ type: "text", text: JSON.stringify({ observation_id: await ragKgManager.correctObservation(validatedArgs.observation_id, validatedArgs.content, validatedArgs.change_kind ?? 'correction', validatedArgs.reason) }, null, 2) }] };
+                case "retractObservation":
+                    await ragKgManager.retractObservation(validatedArgs.observation_id, validatedArgs.reason);
+                    return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'retracted' }, null, 2) }] };
+                case "restoreObservation":
+                    await ragKgManager.restoreObservation(validatedArgs.observation_id, validatedArgs.reason);
+                    return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'active' }, null, 2) }] };
+                case "approveObservation":
+                    await ragKgManager.approveObservation(validatedArgs.observation_id, validatedArgs.reason);
+                    return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'active' }, null, 2) }] };
+                case "declineObservation":
+                    await ragKgManager.declineObservation(validatedArgs.observation_id, validatedArgs.reason);
+                    return { content: [{ type: "text", text: JSON.stringify({ observation_id: validatedArgs.observation_id, status: 'retracted' }, null, 2) }] };
+                case "purgeObservation":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.purgeObservation(validatedArgs.observation_id, validatedArgs.confirm), null, 2) }] };
+                case "getObservationHistory":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getObservationHistory({
+                                    entity_name: validatedArgs.entity_name,
+                                    observation_id: validatedArgs.observation_id,
+                                    root_id: validatedArgs.root_id,
+                                }), null, 2) }] };
+                case "deleteEntities":
+                    await ragKgManager.deleteEntities(validatedArgs.entityNames);
+                    return { content: [{ type: "text", text: "Entities deleted successfully" }] };
+                case "deleteObservations":
+                    // v3.6 (spec §5c, breaking): structured per-entity results replace the
+                    // bare success string — mixed embedded/queued/no-op states are visible.
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.deleteObservations(validatedArgs.deletions), null, 2) }] };
+                case "deleteRelations":
+                    await ragKgManager.deleteRelations(validatedArgs.relations);
+                    return { content: [{ type: "text", text: "Relations deleted successfully" }] };
+                case "updateRelations":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.updateRelations(validatedArgs.updates), null, 2) }] };
+                case "readGraph":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.readGraph(), null, 2) }] };
+                case "searchNodes":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.searchNodes(validatedArgs.query, validatedArgs.limit || 10, validatedArgs.since, validatedArgs.until), null, 2) }] };
+                case "openNodes":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.openNodes(validatedArgs.names), null, 2) }] };
+                case "getNeighbors":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getNeighbors(validatedArgs.entityNames, validatedArgs.depth || 1, validatedArgs.relationType), null, 2) }] };
+                // New RAG tools
+                case "storeDocument":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.storeDocument(validatedArgs.id, validatedArgs.content, validatedArgs.metadata || {}), null, 2) }] };
+                case "chunkDocument":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.chunkDocument(validatedArgs.documentId, { maxTokens: validatedArgs.maxTokens, overlap: validatedArgs.overlap }), null, 2) }] };
+                case "embedChunks":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.embedChunks(validatedArgs.documentId), null, 2) }] };
+                case "extractTerms":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.extractTerms(validatedArgs.documentId, { minLength: validatedArgs.minLength, includeCapitalized: validatedArgs.includeCapitalized, customPatterns: validatedArgs.customPatterns }), null, 2) }] };
+                case "linkEntitiesToDocument":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.linkEntitiesToDocument(validatedArgs.documentId, validatedArgs.entityNames), null, 2) }] };
+                case "hybridSearch":
+                    const limit = typeof validatedArgs.limit === 'number' ? validatedArgs.limit : 5;
+                    // v5.3.0: graph is opt-in — only an explicit true enables the re-ranker (schema default false).
+                    const useGraph = validatedArgs.useGraph === true;
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.hybridSearch(validatedArgs.query, limit, useGraph), null, 2) }] };
+                case "getDetailedContext":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getDetailedContext(validatedArgs.chunkId, validatedArgs.includeSurrounding !== false), null, 2) }] };
+                case "getKnowledgeGraphStats":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getKnowledgeGraphStats(), null, 2) }] };
+                case "deleteDocuments":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.deleteDocuments(validatedArgs.documentIds), null, 2) }] };
+                case "listDocuments":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.listDocuments(validatedArgs.includeMetadata !== false), null, 2) }] };
+                case "syncDocumentFromFile":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.syncDocumentFromFile(validatedArgs.path, validatedArgs.documentId, {
+                                    metadata: validatedArgs.metadata,
+                                    content: validatedArgs.content,
+                                    excludePattern: validatedArgs.excludePattern,
+                                    entityNames: validatedArgs.entityNames,
+                                    chunkParams: validatedArgs.chunkParams,
+                                }), null, 2) }] };
+                // NEW: Entity embedding tools
+                case "embedAllEntities":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.embedAllEntities(), null, 2) }] };
+                // NEW: Export/Import tools
+                case "exportGraph":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.exportGraph(), null, 2) }] };
+                case "importGraph":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.importGraph(validatedArgs.data, { merge: validatedArgs.merge !== false }), null, 2) }] };
+                // NEW: Migration tools
+                case "getMigrationStatus":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getMigrationStatus(), null, 2) }] };
+                case "runMigrations":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.runMigrations(), null, 2) }] };
+                case "rollbackMigration":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.rollbackMigration(validatedArgs.targetVersion), null, 2) }] };
+                // Graph Analytics tools (graphology)
+                case "getGraphMetrics":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.getGraphMetrics(validatedArgs.entityNames, validatedArgs.metrics, validatedArgs.limit || 10), null, 2) }] };
+                case "detectCommunities":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.detectCommunities(validatedArgs.resolution || 1.0), null, 2) }] };
+                case "analyzeGraphStructure":
+                    return { content: [{ type: "text", text: JSON.stringify(await ragKgManager.analyzeGraphStructure(), null, 2) }] };
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+        });
     }
     catch (error) {
         // v3.6 (spec §5c): machine-distinguishable failures. Embedding-gate errors
@@ -4301,6 +4577,7 @@ async function main() {
             if (shuttingDown)
                 return;
             shuttingDown = true;
+            ragKgManager.shuttingDown = true; // no reopen inside the exit window (wal-sidecar-guard)
             // Synchronously, before anything is awaited: a host may SIGKILL before the settle
             // sequence below completes (codex: ~185 ms after SIGTERM).
             ragKgManager.checkpointWal();
@@ -4325,6 +4602,7 @@ async function main() {
         // Ctrl+Break; registering them is harmless where they never fire.
         process.on('SIGHUP', shutdown);
         process.on('SIGBREAK', shutdown);
+        ragKgManager.onFatal = shutdown; // a database that cannot be reopened ends the server (wal-sidecar-guard)
         ragKgManager.startWalKeeper();
         process.on('exit', () => { try {
             ragKgManager.cleanup();

package/dist/src/backfillCoordinator.d.ts

@@ -35,6 +35,7 @@ export declare class BackfillCoordinator {
     private kickTimer;
     private sweepTimer;
     private shuttingDown;
+    private connLossReruns;
     private scanning;
     private scanPromise;
     private rerunRequested;

package/dist/src/backfillCoordinator.js

@@ -14,6 +14,15 @@
 // kick() merely triggers a debounced scan. All reconciliation writes are
 // per-row transactions with a CAS re-check so a foreground embed that lands
 // first is never downgraded (6R note 3).
+// A handle closed by the engine's reopen (wal-sidecar-guard), or an I/O error from a sidecar the
+// sync client swapped out: the run was cut, not broken.
+const CONN_LOSS_RERUN_MAX = 3;
+function isConnectionLoss(e) {
+    const code = e?.code;
+    if (typeof code === 'string' && code.startsWith('SQLITE_IOERR'))
+        return true;
+    return e instanceof Error && /database connection is not open/i.test(e.message);
+}
 const RECON_BATCH = 50;
 const KICK_DEBOUNCE_MS = 200;
 const SWEEP_MS = 5 * 60_000;
@@ -25,6 +34,7 @@ export class BackfillCoordinator {
     kickTimer = null;
     sweepTimer = null;
     shuttingDown = false;
+    connLossReruns = 0;
     scanning = false;
     scanPromise = null;
     rerunRequested = false;
@@ -178,6 +188,7 @@ export class BackfillCoordinator {
             if (remaining !== 0)
                 throw new Error(`complete invariant violated: ${remaining} unreconciled vectors remain`);
             this.recon = 'complete';
+            this.connLossReruns = 0;
             this.snapshot = null;
             console.error('✅ provenance reconciliation complete');
             this.kick();
@@ -190,6 +201,18 @@ export class BackfillCoordinator {
                 this.reconPromise = null;
                 return;
             }
+            if (isConnectionLoss(e) && this.connLossReruns < CONN_LOSS_RERUN_MAX) {
+                // The engine reopened the connection under us (wal-sidecar-guard). Not broken: run
+                // again on the new handle. If there is no handle right now (reopen failed), the engine
+                // starts reconciliation itself once it reopens.
+                this.connLossReruns++;
+                this.recon = 'pending';
+                this.reconPromise = null;
+                if (this.deps.db())
+                    setTimeout(() => { void this.runReconciliation(); }, 0).unref?.();
+                console.error(`↻ reconciliation interrupted by a reconnect — rerun ${this.connLossReruns}/${CONN_LOSS_RERUN_MAX}`);
+                return;
+            }
             this.recon = 'failed';
             this.reconError = e instanceof Error ? e.message : String(e);
             console.error(`❌ reconciliation failed — vector search stays disabled: ${this.reconError}`);

package/dist/src/tools/knowledge-graph-tools.js

@@ -277,7 +277,7 @@ export const addObservationsTool = {
 };
 // === HYBRID SEARCH TOOL ===
 const hybridSearchCapability = {
-    description: 'Perform advanced hybrid search combining vector similarity with knowledge graph traversal',
+    description: 'Perform hybrid search over vector and FTS5 candidates with default reciprocal rank fusion and an optional legacy graph re-ranker',
     parameters: {
         type: 'object',
         properties: {
@@ -300,7 +300,8 @@ const hybridSearchCapability = {
     },
 };
 const hybridSearchDescription = () => `<description>
-Hybrid document search: vector similarity + FTS5 BM25 over document chunks, with an **opt-in** knowledge-graph re-ranker.
+Hybrid document search: vector similarity + FTS5 BM25 over document chunks, fused by rank (reciprocal rank fusion,
+k=60, so an exact identifier that only FTS5 finds can still enter the returned top results), with an **opt-in** knowledge-graph re-ranker.
 Default (useGraph false) is the harm-reduced default for finding a fact you know exists (known-item retrieval).
 useGraph: true is a legacy/experimental re-ranker kept for backward compatibility and controlled evaluation — it does not
 add candidates, it only re-orders the vector/FTS pool, and measured on three real corpora (2026-08-17) it pushed the exact
@@ -310,14 +311,14 @@ chunk out of the top-5 in ~40% of known-item queries. For relationship explorati
 <importantNotes>
 - (!important!) **Graph re-ranking is opt-in (default false since v5.3.0)** — it re-orders candidates by matched/connected entity links, which is measured to hurt known-item retrieval; enable it only for backward compatibility or controlled evaluation
 - (!important!) Graph re-ranking does not generate candidates — for "what is connected to X" use openNodes -> getNeighbors
-- (!important!) Results include similarity scores, graph boost, and hybrid rankings
+- (!important!) relevance_score is a RANK score on the default call: 1/(60 + vector rank) + 1/(60 + FTS rank), at most 2/61; it is not a similarity or probability and is only comparable within one call (vector_similarity and fts_boost are reported alongside)
 - (!important!) **Best results when knowledge graph is well-populated** with entities and relationships
 </importantNotes>
 
 <whenToUseThisTool>
 - When you need comprehensive search across documents and knowledge
 - For complex queries requiring conceptual understanding
-- When exploring relationships between concepts
+- Exact identifiers (file names, setting keys, function names, hashes) as well as natural-language questions
 - **Before making decisions** - to gather all relevant information
 - When researching topics that span multiple domains
 - For discovery of implicit connections and patterns
@@ -325,7 +326,8 @@ chunk out of the top-5 in ~40% of known-item queries. For relationship explorati
 
 <features>
 - Vector similarity search using sentence transformers
-- Knowledge graph traversal for conceptual enhancement
+- Rank fusion of vector and FTS5 candidates: an exact term found only by FTS5 can enter the returned top results even when vector candidates are present
+- Optional legacy graph re-ranker (re-orders only; no traversal — use openNodes -> getNeighbors)
 - Hybrid scoring combining multiple relevance signals
 - Entity association highlighting
 - Configurable result limits and graph usage
@@ -333,7 +335,7 @@ chunk out of the top-5 in ~40% of known-item queries. For relationship explorati
 </features>
 
 <bestPractices>
-- Use natural language queries rather than keywords
+- Natural-language questions and exact identifiers both work; pass the identifier itself when you know it
 - Keep graph re-ranking off for "find the fact I know exists"; for "what is connected to this" use openNodes -> getNeighbors, not useGraph
 - Start with broader queries, then narrow down based on results
 - Review entity associations to understand why results were selected
@@ -342,7 +344,7 @@ chunk out of the top-5 in ~40% of known-item queries. For relationship explorati
 </bestPractices>
 
 <parameters>
-- query: Natural language search query (string, required)
+- query: Search query — a natural-language question or an exact term/identifier (string, required)
 - limit: Maximum results to return, default 5 (number, optional)
 - useGraph: Enable knowledge graph re-ranking, default false / opt-in (boolean, optional)
 </parameters>

package/docs/UPDATING.md

@@ -108,6 +108,52 @@ path and holder pid (e.g. `.download-<key>.lock`). Verify the holder process
 is genuinely gone or hung (`ps -p <pid>`), then remove the lock file manually;
 the next start becomes a clean download owner.
 
+## v6.4.0 (schema v14, unchanged): `hybridSearch` default = rank fusion, summaries opt-in
+
+(Release candidate `6.4.0-rc.1` on the `next` dist-tag first; `latest` stays 6.3.2 until the published artifact
+passes a canary against a real project database.)
+
+**What changed.** (1) The per-result summary path runs only with `RAG_MEMORY_SEARCH_SUMMARIES=on` (it used to
+run unless the variable was `off`; `off` still means off). (2) With summaries off and `useGraph: false` — the
+default call — results are ranked by reciprocal rank fusion of the vector list and the FTS5 list:
+`relevance_score = 1/(60 + vector rank) + 1/(60 + FTS rank)`, a list a chunk is absent from contributes 0.
+Healthy-path candidate gathering and depth are unchanged. If vector search fails after an earlier query variant
+succeeded, the call now discards those partial vector candidates and returns a true FTS-only result (the previous
+version could keep them while reporting `fts-only`). `summaries=on` or `useGraph: true` keep the 6.3.2 formula
+(`max(vector_similarity, summary relevance) + graph boost + FTS term`) unchanged.
+
+**Why.** Measured 2026-10-03 on the frozen eval snapshots (spec `specs/changes/search-fusion-rrf/proposal.md`):
+the summary path embedded ~400 sentence fragments per search (median 121 s) and its unbounded context boost let
+vector-0 chunks take rank 1 (known-item hit@1 9/10 with summaries off vs 4/10 on). With summaries off, a chunk
+found only by FTS scored at most 0.0164 against ~0.4-0.6 for every vector candidate, so exact-identifier
+queries surfaced their target in the top 10 for 7/20 queries although FTS ranked it first for 17/20. Rank fusion:
+18/20, and worse than the old formula on 0 of 203 queries across three corpora.
+
+**Query input (same release).** With the default model (bge-m3) queries are embedded as raw text; a custom
+`EMBEDDING_MODEL` keeps the previous query instruction (the evidence below is for bge-m3 only). Up to 6.3.2 the loader prepended the bge-v1.5
+instruction `Represent this sentence for searching relevant passages: ` to every query (hybridSearch, searchNodes,
+graph seeds) while stored vectors were embedded without it; the bge-m3 model card says the model needs no query
+instruction. Measured on the frozen snapshots: hybridSearch paraphrase hit@10 7 -> 9 / 20 and MRR 0.217 -> 0.275,
+identifier hit@1 7 -> 8, known-item unchanged on hub / uap and hit@1 +1 on hal; searchNodes known-item (40 entities per
+corpus) hit@10 unchanged, hit@1 -1 / -1 / +1. No re-index: only query vectors change; rolling back means a restart.
+`server_meta.query_prefix_version` is a diagnostic marker written at init (2 = raw queries with the default model,
+1 = instruction); it does not prove what the last query used.
+
+**What a caller notices.** On the default call `relevance_score` is a rank score — at most 2/61 ≈ 0.0328, no lower
+bound (a chunk in one list at rank r gets 1/(60+r)), comparable only within one call; do not threshold it against
+old values or across queries/modes. `vector_similarity` and `fts_boost` keep their meaning. `content_summary`
+/ `key_highlight` are preview slices unless summaries are turned on. The fragment-summary work is gone from default
+searches: measured query-cached medians were 20 / 10 / 6 ms on the frozen hub / uap / hal runs; with the query
+embedding cache cleared before every call (one Mac, final build) medians were about 220 / 228 /
+203 ms (max 888 ms). Other machines and corpora are unmeasured — this is not a universal millisecond guarantee. With
+`useGraph: true` and the variable unset, summaries are now off; set `RAG_MEMORY_SEARCH_SUMMARIES=on` to reproduce
+the previous summary-enabled graph path.
+
+**Fleet rollout.** No migration. Recommended like v5.3.0: publish an rc on the `next` dist-tag first, run it
+against a real project database (identifier query + known-item probe), then promote to `latest`.
+Regression locks: `test/search-fusion-rrf.test.mjs`, `test/search-summaries-off.test.mjs`, and
+`test/graph-context-explain.test.mjs` (legacy path byte-identical with summaries on).
+
 ## v5.3.0 (schema v14, unchanged): `hybridSearch` graph re-ranking is opt-in
 
 **What changed.** `useGraph` defaults to `false` (was `true`) — in the manager signature, the tool JSON
@@ -207,8 +253,10 @@ the real v14 (this is exactly how code-v8 never ran in production).
 **Diagnostic env (v5)**: `RAG_MEMORY_SEARCH_SUMMARIES=off` disables the per-result
 sentence-similarity summaries in `hybridSearch` (which embed every sentence of every
 candidate — 100+ inferences, 90-120s cold per search, measured). Off = preview-slice
-summaries, `relevance_score` 0, ranking rests on vector similarity + boosts. Default
-unchanged. The 3-arm release harness sets this uniformly across all arms.
+summaries, the internal summary relevance is 0 (the response's `relevance_score` is still the final score) and
+ranking rests on vector similarity + boosts. **Superseded by the next
+release: summaries are off by default and opt-in with `=on`** (see the section above). The 3-arm release
+harness sets this uniformly across all arms.
 
 ## v3.6 breaking response changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "rag-memory-epf-mcp",
- "version": "6.3.1",
+ "version": "6.4.0-rc.1",
  "engines": {
   "node": ">=24"
  },
@@ -45,7 +45,7 @@
   "prepare": "npm run build",
   "watch": "tsc --watch",
   "verify:invariants": "node test/chunk-invariants.test.mjs",
-  "verify:engine": "node test/engine-smoke.test.mjs && node test/launch-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs && node test/entity-embed-cap.test.mjs && node test/migration12.test.mjs && node test/model-cache.test.mjs && node test/embedding-gate.test.mjs && node test/lazy-boot.test.mjs && node test/reconciliation.test.mjs && node test/backfill.test.mjs && node test/fts-query.test.mjs && node test/search-contracts.test.mjs && node test/tool-contracts.test.mjs && node test/bounded-exit.test.mjs && node test/observation-schema.test.mjs && node test/search-graph-default.test.mjs && node test/observation-migration.test.mjs && node test/observation-lifecycle.test.mjs && node test/observation-contracts.test.mjs && node test/observation-search.test.mjs && node test/observation-cascade.test.mjs && node test/observation-realdata.test.mjs && node test/chunker-c.test.mjs && node test/migration14.test.mjs && node test/chunk-params-validation.test.mjs && node test/vector-reuse.test.mjs && node test/entity-range-linking.test.mjs && node test/alias-link-gate.test.mjs && node test/entity-name-boundary.test.mjs && node test/stats-chunking.test.mjs && node test/migration14-realdata.test.mjs && node test/migration14-realdata-sync.test.mjs && node test/search-summaries-off.test.mjs && node test/document-return-contracts.test.mjs && node test/observation-date-prefix.test.mjs && node test/delete-entities-cascade.test.mjs && node test/delete-entities-kg-hygiene.test.mjs && node test/backup-publish-portable.test.mjs && node test/graph-context-explain.test.mjs && node test/eval-graph-role-libs.test.mjs && node test/eval-graph-role-t5b.test.mjs && node --test test/eval-graph-role-t8-fix.test.mjs && node --test test/eval-graph-role-t7-upstream.test.mjs && node --test test/eval-graph-role-t11-decision.test.mjs && node --test test/eval-graph-role-prereq-fix.test.mjs && node test/db-path.test.mjs && node test/mmap-option.test.mjs && node test/wal-exit.test.mjs",
+  "verify:engine": "node test/engine-smoke.test.mjs && node test/launch-smoke.test.mjs && node test/sync-atomicity.test.mjs && node test/dedup.test.mjs && node test/search-degradation.test.mjs && node test/entity-embed-cap.test.mjs && node test/migration12.test.mjs && node test/model-cache.test.mjs && node test/embedding-gate.test.mjs && node test/lazy-boot.test.mjs && node test/reconciliation.test.mjs && node test/backfill.test.mjs && node test/fts-query.test.mjs && node test/search-contracts.test.mjs && node test/tool-contracts.test.mjs && node test/bounded-exit.test.mjs && node test/observation-schema.test.mjs && node test/search-graph-default.test.mjs && node test/observation-migration.test.mjs && node test/observation-lifecycle.test.mjs && node test/observation-contracts.test.mjs && node test/observation-search.test.mjs && node test/observation-cascade.test.mjs && node test/observation-realdata.test.mjs && node test/chunker-c.test.mjs && node test/migration14.test.mjs && node test/chunk-params-validation.test.mjs && node test/vector-reuse.test.mjs && node test/entity-range-linking.test.mjs && node test/alias-link-gate.test.mjs && node test/entity-name-boundary.test.mjs && node test/stats-chunking.test.mjs && node test/migration14-realdata.test.mjs && node test/migration14-realdata-sync.test.mjs && node test/search-summaries-off.test.mjs && node test/search-fusion-rrf.test.mjs && node test/query-input.test.mjs && node test/document-return-contracts.test.mjs && node test/observation-date-prefix.test.mjs && node test/delete-entities-cascade.test.mjs && node test/delete-entities-kg-hygiene.test.mjs && node test/backup-publish-portable.test.mjs && node test/graph-context-explain.test.mjs && node test/eval-graph-role-libs.test.mjs && node test/eval-graph-role-t5b.test.mjs && node --test test/eval-graph-role-t8-fix.test.mjs && node --test test/eval-graph-role-t7-upstream.test.mjs && node --test test/eval-graph-role-t11-decision.test.mjs && node --test test/eval-graph-role-prereq-fix.test.mjs && node test/db-path.test.mjs && node test/mmap-option.test.mjs && node test/wal-exit.test.mjs && node test/wal-sidecar-guard.test.mjs",
   "test": "npm run build && npm run verify:invariants && npm run verify:engine",
   "prepublishOnly": "npm run build && npm run verify:invariants && npm run verify:engine"
  },