rag-memory-epf-mcp 6.3.0 → 6.3.2

package/README.md

@@ -154,6 +154,46 @@ storeDocument(id, content, metadata)
 
 ## Changelog
 
+### 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:
+  on a 1 s tick whenever the `-wal` file has bytes in it, ~200 ms after a tool call, first thing in the
+  signal handler, and before closing. SQLite folds the WAL only when the *last* connection closes and
+  only if that close gets to run; with several engines on one file, or a host that kills the engine
+  (measured: codex-cli 0.155.1 sends SIGTERM and SIGKILLs ~185 ms later; Windows terminates children
+  outright), frames stayed in the WAL — on 6.3.0 a fresh database sat at 4 KB main + 663 KB WAL for as
+  long as the engine ran. In a cloud-synced folder such a WAL can be replayed onto a main file written
+  by another machine. A write made in the last ~1 s before a hard kill can still be in the WAL; a 0-byte
+  `-wal` and a `-shm` left behind by a hard kill are harmless. Running engines on two machines against
+  the same synced file at the same time is still unsafe.
+- **Changed — SIGHUP and SIGBREAK shut the engine down cleanly.** Closing the terminal or multiplexer
+  pane used to kill the process by default signal action, before the database was closed.
+- No tool, argument, return shape or schema changed.
+
 ### v6.3.0 (2026-09-16)
 
 - **Changed — a relative `DB_FILE_PATH` now resolves against the server's working directory.** It used

package/dist/index.d.ts

@@ -51,6 +51,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 +83,7 @@ export declare class RAGKnowledgeGraphManager {
         gate?: EmbeddingGate;
         __testForceFkOff?: boolean;
     }): Promise<void>;
+    private openConnection;
     private ensureCurrentProfile;
     private buildRealLoader;
     startReconciliation(): Promise<void>;
@@ -101,6 +103,31 @@ export declare class RAGKnowledgeGraphManager {
             description: string;
         }>;
     }>;
+    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;
+    noteActivity(delayMs?: number): void;
     cleanup(): void;
     private _timestampObservation;
     createEntities(entities: Array<Entity & {

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';
@@ -136,6 +137,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 +244,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 +253,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 +283,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() {
@@ -544,6 +576,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);
@@ -593,13 +626,283 @@ export class RAGKnowledgeGraphManager {
             }))
         };
     }
+    // Fold the WAL into the main file and empty it. Returns true when the WAL holds no
+    // frames afterwards.
+    //
+    // Why the engine does this itself instead of leaving it to SQLite: SQLite folds the WAL
+    // only when the LAST connection closes, and only if that close gets to run. Neither holds
+    // here — several engines keep the same file open (one per CLI), and some hosts end the
+    // engine without letting it finish (codex-cli 0.155.1, measured: SIGTERM, then SIGKILL
+    // ~185 ms later; on Windows a child is simply terminated). A WAL with frames that outlives
+    // its process is replayed at the next open against whatever main file is there by then, and
+    // in a cloud-synced folder that can be a main file written by another machine. SQLite does
+    // not check that a WAL belongs to the main file next to it. That corrupted a live database
+    // twice. So the invariant is kept continuously: while idle, the WAL is empty.
+    //
+    // TRUNCATE, not PASSIVE: PASSIVE copies the frames into the main file but leaves them in
+    // the WAL, still valid, still replayable onto a foreign main file.
+    // busy_timeout is dropped to 0 around the call: TRUNCATE runs the busy handler, and a 5 s
+    // stall inside a signal handler or a timer tick is worse than retrying on the next tick.
+    checkpointWal() {
+        if (!this.db)
+            return true;
+        try {
+            const st = fsSync.statSync(DB_FILE_PATH + '-wal', { throwIfNoEntry: false });
+            if (!st || st.size === 0)
+                return true;
+            this.db.pragma('busy_timeout = 0');
+            try {
+                const r = this.db.pragma('wal_checkpoint(TRUNCATE)');
+                return r?.[0]?.busy === 0;
+            }
+            finally {
+                this.db.pragma('busy_timeout = 5000');
+            }
+        }
+        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
+    // the size of the -wal file, not at which tool ran, so background writers (reconciliation,
+    // backfill) are covered as well. noteActivity() only shortens the wait after a tool call.
+    startWalKeeper(tickMs = 1000) {
+        if (this.walTimer)
+            return;
+        this.walTimer = setInterval(() => {
+            try {
+                this.walTick();
+            }
+            catch (e) {
+                console.error(`⚠️ wal tick: ${e.message}`);
+            }
+            this.checkpointWal();
+        }, tickMs);
+        this.walTimer.unref();
+    }
+    noteActivity(delayMs = 200) {
+        if (this.walSoon)
+            return;
+        this.walSoon = setTimeout(() => { this.walSoon = null; this.checkpointWal(); }, delayMs);
+        this.walSoon.unref();
+    }
     cleanup() {
+        this.shuttingDown = true;
+        if (this.walTimer) {
+            clearInterval(this.walTimer);
+            this.walTimer = null;
+        }
+        if (this.walSoon) {
+            clearTimeout(this.walSoon);
+            this.walSoon = null;
+        }
         if (this.encoding) {
             this.encoding.free();
             this.encoding = null;
         }
         this.embeddingCache.clear();
         if (this.db) {
+            // close() folds the WAL only for the last connection; with other engines attached it
+            // would leave every frame behind.
+            this.checkpointWal();
             this.db.close();
             this.db = null;
         }
@@ -4061,116 +4364,120 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         // Validate arguments using our structured schema
         const validatedArgs = validateToolArgs(name, args);
-        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}`);
-        }
+        ragKgManager.noteActivity(); // fold the WAL shortly after this call, whatever it wrote
+        // 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
@@ -4235,6 +4542,10 @@ 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();
             void (async () => {
                 try {
                     await server.close();
@@ -4250,6 +4561,14 @@ async function main() {
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
+        // SIGHUP = the terminal or multiplexer pane was closed. Without a handler the default
+        // action kills the process before 'exit' listeners run, so the database is never closed.
+        // On Windows, Node raises SIGHUP when the console window is closed and SIGBREAK on
+        // 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/package.json

@@ -1,6 +1,6 @@
 {
  "name": "rag-memory-epf-mcp",
- "version": "6.3.0",
+ "version": "6.3.2",
  "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",
+  "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 && 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"
  },