rag-memory-epf-mcp 3.5.2 → 4.0.0

package/dist/index.js

@@ -21,13 +21,59 @@ import modularity from 'graphology-metrics/graph/modularity.js';
 import { getAllMCPTools, validateToolArgs, getSystemInfo } from './src/tools/tool-registry.js';
 // Import migration system
 import { MigrationManager } from './src/migrations/migration-manager.js';
+import { backupBeforeMigration } from './src/backup/preflight.js';
+import { rebuildProjection, deleteStaleKgChunks } from './src/observations/projection.js';
+import { addRevision, correctRevision, transitionStatus, linkSources, nextProjectionOrder } from './src/observations/lifecycle.js';
+import { getObservationHistory } from './src/observations/history.js';
 // Import chunk text algorithm (extracted for publish-time invariant testing)
 import { chunkText as splitTextIntoChunks } from './src/chunkText.js';
 import { migrations } from './src/migrations/migrations.js';
+// v3.6 lite install: model lifecycle + version-independent cache (A′ boundary)
+import { EmbeddingGate, GateNotReadyError, GateDisabledError, TerminalConfigError } from './src/embeddingGate.js';
+import { resolveModelCacheDir, preflightCacheDir, artifactKey, ModelDownloadLock, handleLoaderFailure } from './src/modelCache.js';
+import { BackfillCoordinator } from './src/backfillCoordinator.js';
+import os from 'node:os';
 import { createHash } from 'crypto';
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 const PKG_VERSION = require('../package.json').version;
+// v3.6: runtime Node floor (engines is advisory only under default npm config).
+// Limitation: static native imports above may fail before this runs on very old
+// Node — documented in docs/UPDATING.md.
+const NODE_MAJOR = Number(process.versions.node.split('.')[0]);
+function assertNodeVersion() {
+    if (NODE_MAJOR < 24) {
+        console.error(`❌ rag-memory-epf-mcp v${PKG_VERSION} requires Node >= 24 (current: ${process.versions.node}).`);
+        console.error('   See docs/UPDATING.md for the supported runtime matrix.');
+        process.exitCode = 1;
+        throw new Error('unsupported Node version');
+    }
+}
+// v3.6: strip tokens / auth material / long URLs from operator-facing error text.
+function sanitizeErrorMessage(msg) {
+    return msg
+        .replace(/(hf_|api[_-]?key=|authorization:\s*)\S+/gi, '$1[redacted]')
+        .replace(/https?:\/\/\S{60,}/g, '[url]')
+        .slice(0, 500);
+}
+// v3.6: startup self-report banner (version reliability — spec §8).
+function printBanner(opts) {
+    console.error(`🚀 rag-memory-epf-mcp v${PKG_VERSION} | node v${process.versions.node} | model ${opts.model}@${opts.revision} (${opts.dtype}) | cache ${opts.cachePath} | db ${opts.dbPath}`);
+}
+// v3.6 (spec §5): ONE FTS5 literal-query compiler shared by chunk and entity
+// search — raw user input can never produce MATCH syntax errors or trigger
+// 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).
+export function compileFtsLiteralQuery(q) {
+    const sanitized = q.replace(/["\*\(\)\-]/g, ' ').trim();
+    if (!sanitized)
+        return null;
+    const terms = sanitized.split(/\s+/).filter(t => t.length > 0);
+    if (terms.length === 0)
+        return null;
+    return terms.map(t => `"${t}"`).join(' OR ');
+}
 // Configure Hugging Face transformers for better compatibility
 if (env.backends?.onnx?.wasm) {
     env.backends.onnx.wasm.wasmPaths = './node_modules/@huggingface/transformers/dist/';
@@ -40,6 +86,21 @@ const DB_FILE_PATH = process.env.DB_FILE_PATH
         : path.join(path.dirname(fileURLToPath(import.meta.url)), process.env.DB_FILE_PATH)
     : defaultDbPath;
 const EMBEDDING_MODEL = process.env.EMBEDDING_MODEL || 'Xenova/bge-m3';
+// v3.5 default model config — grandfathering legacy vectors is only automatic
+// when the current config matches this (spec §6b custom-model guard). An
+// EXPLICIT `EMBEDDING_MODEL=Xenova/bge-m3` counts as default: same weights,
+// same pin, same grandfather policy (beta 1R consistency fix).
+const IS_DEFAULT_MODEL_CONFIG = !process.env.EMBEDDING_MODEL || process.env.EMBEDDING_MODEL === 'Xenova/bge-m3';
+// Default model pinned to an upstream commit (spec §6c): a shared version-
+// independent cache must never silently swap weights under 'main'. Verified
+// 2026-07-18 via `git ls-remote https://huggingface.co/Xenova/bge-m3` — the
+// same revision the local v3.5 cache was downloaded from. Custom models stay
+// on 'main' (their vectors are never auto-grandfathered anyway).
+const MODEL_REVISION = IS_DEFAULT_MODEL_CONFIG ? '4de13258303883538bd53b696b452bf8099f0858' : 'main';
+const MODEL_DTYPE = 'fp16';
+// Entity embedding text builder version — mixed into entity input hashes so a
+// builder change re-backfills entities without touching chunk vectors (spec §6c).
+const TEXT_BUILDER_VERSION = 'tb1';
 // Safe rowid for vec0 virtual tables (require literal integer, not parameterized)
 // Trim incomplete UTF-8 multi-byte sequences at chunk boundaries.
 // Continuation bytes match 10xxxxxx (0x80-0xBF); lead bytes indicate how many
@@ -59,18 +120,26 @@ function safeRowid(value) {
 export class RAGKnowledgeGraphManager {
     db = null;
     encoding = null;
-    embeddingModel = null;
-    modelInitialized = false;
+    gate;
+    embeddingsMode = 'lazy';
+    currentProfileId = 0;
+    // Automatic grandfathering of legacy vectors is only allowed under the v3.5
+    // default model config, or with the explicit trust opt-in (spec §6b guard).
+    grandfatherAllowed = IS_DEFAULT_MODEL_CONFIG || process.env.RAG_MEMORY_TRUST_LEGACY_VECTORS === '1';
+    coordinator = null;
     embeddingCache = new Map();
     EMBEDDING_CACHE_MAX = 500;
     dictionaryCache = null;
+    // v3.6 (spec §3): initialize = DB + migrations + profile only. The embedding
+    // model is NEVER awaited here — main() connects the MCP server first and the
+    // gate loads in the background (lazy) or is awaited explicitly (eager).
+    // __testForceFkOff: 음성 대조군 전용. FK 게이트가 실제로 부팅을 막는지 시험한다.
+    // 이름에 __test 를 박아 둔 이유는 이것이 프로덕션 설정 표면이 아니라는 것을
+    // 호출부에서 읽히게 하기 위해서다.
     async initialize(opts = {}) {
         console.error('🚀 Initializing RAG Knowledge Graph MCP Server...');
-        // Initialize database
         this.db = new Database(DB_FILE_PATH);
-        // Load sqlite-vec extension
         sqliteVec.load(this.db);
-        // SQLite performance & safety optimizations
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('synchronous = NORMAL');
         this.db.pragma('busy_timeout = 5000');
@@ -78,37 +147,332 @@ export class RAGKnowledgeGraphManager {
         this.db.pragma('temp_store = MEMORY');
         this.db.pragma('mmap_size = 268435456');
         this.db.pragma('foreign_keys = ON');
-        // Initialize tiktoken
-        this.encoding = get_encoding("cl100k_base");
-        // Initialize embedding model (skippable for tests / FTS-only environments)
-        if (!opts.skipModel) {
-            await this.initializeEmbeddingModel();
-        }
-        else {
-            console.error('⏭️  Skipping embedding model load (skipModel=true)');
+        // 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.`);
+            }
         }
-        // Run database migrations
+        this.encoding = get_encoding("cl100k_base");
         await this.runMigrations();
-        console.error('✅ RAG-enabled knowledge graph initialized');
-        // Log system info
+        this.currentProfileId = this.ensureCurrentProfile();
+        this.embeddingsMode = opts.skipModel
+            ? 'off'
+            : (process.env.RAG_MEMORY_EMBEDDINGS || 'lazy');
+        if (!['lazy', 'eager', 'off'].includes(this.embeddingsMode))
+            this.embeddingsMode = 'lazy';
+        this.gate = opts.gate ?? new EmbeddingGate({
+            mode: this.embeddingsMode,
+            loadModel: () => this.buildRealLoader(),
+            onReady: () => this.coordinator?.kick(),
+        });
+        // Late-bound deps (closures): tests swap manager.gate / flip the guard.
+        this.coordinator = new BackfillCoordinator({
+            db: () => this.db,
+            gateIsReady: () => this.gate.isReady,
+            gateIsDisabled: () => this.gate.isDisabled,
+            mode: () => this.embeddingsMode,
+            grandfatherAllowed: () => this.grandfatherAllowed,
+            currentProfileId: () => this.currentProfileId,
+            buildEntityInputHash: (entityId) => this.entityInputHash(entityId),
+            hashEntityText: (text) => this.hashWithBuilderVersion(text),
+            chunkInputHash: (text) => createHash('sha256').update(text).digest('hex'),
+            reembedEntity: async (entityId) => this.embedEntity(entityId, 'backfill'),
+            reembedChunk: async (rowid) => this.reembedChunkByRowid(rowid),
+        });
+        console.error('✅ RAG-enabled knowledge graph initialized (embedding model deferred)');
         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)`);
     }
-    async initializeEmbeddingModel() {
+    // Upsert the stored-vector compatibility profile (spec §6c layer 2) and record
+    // retrieval config in server_meta (layer 3 — never a backfill trigger).
+    ensureCurrentProfile() {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const dims = 1024;
+        if (dims !== 1024)
+            throw new Error('unsupported embedding dims (vec0 tables are fixed at 1024)'); // fail-fast contract
+        this.db.prepare(`INSERT OR IGNORE INTO embedding_profiles
+      (model_id, revision, dtype, dims, pooling, normalize) VALUES (?,?,?,?,?,?)`)
+            .run(EMBEDDING_MODEL, MODEL_REVISION, MODEL_DTYPE, dims, 'cls', 1);
+        const row = this.db.prepare(`SELECT id FROM embedding_profiles
+      WHERE model_id=? AND revision=? AND dtype=? AND dims=? AND pooling=? AND normalize=?`)
+            .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();
+        return row.id;
+    }
+    // Real model loader used by the gate: version-independent cache dir with a
+    // cross-process download lock. Preflight failure throws (gate -> failed);
+    // silently falling back to the package-internal cache is forbidden (spec §7).
+    async buildRealLoader() {
+        const cacheDir = resolveModelCacheDir(process.env, process.platform, os.homedir());
+        const pf = preflightCacheDir(cacheDir);
+        if (!pf.ok)
+            throw new Error(`model cache dir not writable (${cacheDir}): ${pf.error}`);
+        const key = artifactKey(EMBEDDING_MODEL, MODEL_REVISION, MODEL_DTYPE);
+        const lock = new ModelDownloadLock(cacheDir, key);
+        // Shutdown aborts the lock wait via the gate's AbortController (spec §3).
+        console.error('⏳ acquiring model download lock...'); // deterministic lock-wait marker (5R test residual)
+        const role = await lock.acquireOrWait({ timeoutMs: 10 * 60_000, signal: this.gate.abort.signal });
         try {
-            console.error(`🤖 Loading embedding model: ${EMBEDDING_MODEL} (1024-dim, 100+ languages)...`);
-            // Configure environment to allow remote model downloads
+            this.gate.markDownloading();
             env.allowRemoteModels = true;
             env.allowLocalModels = true;
-            this.embeddingModel = await pipeline('feature-extraction', EMBEDDING_MODEL, { revision: 'main', dtype: 'fp16' });
-            this.modelInitialized = true;
-            console.error(`✅ ${EMBEDDING_MODEL} model loaded successfully (fp16)`);
+            console.error(`🤖 Loading embedding model: ${EMBEDDING_MODEL} (1024-dim, cache=${cacheDir})...`);
+            const model = await pipeline('feature-extraction', EMBEDDING_MODEL, { revision: MODEL_REVISION, dtype: MODEL_DTYPE, cache_dir: cacheDir });
+            // dims fail-fast (spec §2 / beta B8): probe the ACTUAL output length — a
+            // 384/768-dim custom model must fail here with a clear message, not at
+            // every subsequent vector write.
+            const probe = await model('dimension probe', { pooling: 'cls', normalize: true });
+            const actualDims = probe.data.length;
+            if (actualDims !== 1024) {
+                // Config incompatibility, NOT cache corruption (beta 2R B3): the
+                // download and load both succeeded — quarantining or retrying cannot
+                // change the model's dimensions.
+                if (role === 'owner')
+                    lock.markComplete(); // cache itself is valid
+                throw new TerminalConfigError(`embedding model ${EMBEDDING_MODEL} outputs ${actualDims} dims — this engine's vec0 tables are fixed at 1024. Use a 1024-dim model.`);
+            }
+            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));
+            };
         }
-        catch (error) {
-            console.error('❌ Failed to load embedding model:', error instanceof Error ? error.message : error);
-            console.error('⚠️  Semantic search will be unavailable. Other tools (CRUD, graph queries) still work.');
-            console.error('💡 Fix: Ensure ONNX model cache is accessible. Try: rm -rf ~/.npm/_onnx_models && restart.');
-            this.modelInitialized = false;
+        catch (e) {
+            // Cache policy by CAUSE and ROLE (beta 2R B3 -> 4R M1 -> 5R M1), unit-
+            // tested in modelCache: config errors touch nothing; integrity errors
+            // invalidate the marker, and only a lock-holding OWNER may quarantine
+            // (a ready-role process racing other readers never deletes shared
+            // files); OOM/network/unknown preserve everything.
+            const action = handleLoaderFailure({
+                role, error: e, lock, cacheDir, modelId: EMBEDDING_MODEL,
+                terminal: e instanceof TerminalConfigError,
+            });
+            if (action === 'quarantined')
+                console.error('🧹 cache-integrity failure (owner) — model cache quarantined');
+            else if (action === 'marker-invalidated')
+                console.error('… cache-integrity failure (reader) — marker dropped, next retry re-proves as locked owner');
+            else if (!(e instanceof TerminalConfigError))
+                console.error('… non-integrity load failure — model cache preserved');
+            throw e;
+        }
+        finally {
+            lock.release();
+        }
+    }
+    // Background provenance reconciliation (spec §6b). Runs in parallel with the
+    // model load; vector search and automatic backfill stay closed until it
+    // settles (eligibility barrier in the coordinator).
+    async startReconciliation() {
+        if (!this.coordinator)
+            return;
+        await this.coordinator.runReconciliation();
+        this.coordinator.sweepStart();
+    }
+    // sha256 with the entity text-builder version mixed in: a builder change
+    // re-backfills entities only, never chunks (spec §6c N2).
+    hashWithBuilderVersion(text) {
+        return createHash('sha256').update(`${TEXT_BUILDER_VERSION}\n${text}`).digest('hex');
+    }
+    // Rebuild the CURRENT embedding input hash for an entity. null = entity gone
+    // or malformed observations — reconciliation fail-closes to missing.
+    entityInputHash(entityId) {
+        try {
+            const entity = this.db.prepare(`SELECT name, entityType, observations FROM entities WHERE id = ?`)
+                .get(entityId);
+            if (!entity)
+                return null;
+            const built = this.buildEntityEmbeddingText({
+                name: entity.name,
+                entityType: entity.entityType,
+                observations: JSON.parse(entity.observations),
+            });
+            return this.hashWithBuilderVersion(built.text);
+        }
+        catch {
+            return null;
+        }
+    }
+    // Mutation-path embedding wrapper (spec §5): CRUD success never depends on
+    // model availability. On not-ready/disabled the stale vector is deleted in
+    // the same breath (dirty = missing, §6a-1) and the coordinator is kicked so
+    // the row is recovered without a restart (§5 kick column).
+    async tryEmbedEntity(entityId, priority = 'bulk') {
+        try {
+            const ok = await this.embedEntity(entityId, priority);
+            if (ok) {
+                // Success clears any stale backfill-failure record for this target.
+                this.db.prepare(`DELETE FROM embedding_backfill_failures WHERE kind = 'entity' AND target_id = ?`).run(entityId);
+                this.coordinator?.invalidateCoverage();
+                return 'embedded';
+            }
+            this.invalidateEntityVector(entityId);
+            this.coordinator?.kick();
+            return 'queued';
+        }
+        catch (e) {
+            // Any embedding-layer failure (not-ready, disabled, OR a ready-state
+            // inference error) must not fail the CRUD that already committed. The
+            // vector is invalidated (§6a-1) and recovery is owned by the backfill
+            // scanner with its attempts cap — never by rethrowing here (spec §5).
+            if (!(e instanceof GateNotReadyError) && !(e instanceof GateDisabledError)) {
+                console.error(`⚠️ embedding failed for ${entityId} (queued for backfill): ${e instanceof Error ? e.message : e}`);
+            }
+            this.invalidateEntityVector(entityId);
+            this.coordinator?.kick();
+            return e instanceof GateDisabledError ? 'disabled' : 'queued';
+        }
+    }
+    // §6a-1 (beta B2): the entity change and the stale-vector removal commit in
+    // ONE synchronous transaction, BEFORE any inference await. No window exists
+    // where another tool call can retrieve the pre-mutation vector, and a crash
+    // between mutation and re-embed leaves a clean missing state (backfill
+    // target), never a stale-searchable one.
+    // spec §4.5 단계 1: 관찰 변경 · projection 재합성 · entity vector 무효화 ·
+    // stale KG chunk 제거를 한 트랜잭션으로 묶는다. 하나만 되면 검색이 낡은
+    // 사실을 계속 반환한다.
+    // mutate 가 명시적으로 false 를 반환하면 "아무것도 바꾸지 않았다"는 뜻이고
+    // projection 재합성·벡터 무효화·KG 정리를 건너뛴다. 이 경로가 없으면
+    // 무변경 upsert 나 dedup-only add 가 **정상 벡터를 지우고 재임베딩도 안 해서**
+    // 검색 품질만 깎는다(advisor 구현리뷰 r1 발견 1, 실행 재현).
+    // 반환값 = 실제로 변경이 있었는가.
+    mutateEntityAndInvalidate(entityId, mutate) {
+        let changed = false;
+        const tx = this.db.transaction(() => {
+            changed = mutate() !== false;
+            if (!changed)
+                return;
+            rebuildProjection(this.db, entityId);
+            this.invalidateDerivedForEntity(entityId);
+        });
+        tx();
+        if (changed)
+            this.coordinator?.invalidateCoverage();
+        return changed;
+    }
+    // 관찰이 바뀐 entity 의 파생 상태를 무효화한다: entity vector + stale KG chunk.
+    // **트랜잭션을 열지 않는다** — 호출자가 이미 하나의 단위 안에 있다고 가정한다.
+    //
+    // importGraph 가 이 단계를 건너뛰고 있었다: projection 만 재합성하고 파생 상태를
+    // 그대로 둬서, 이미 존재하는 entity 를 import 로 덮으면 옛 벡터·옛 KG chunk 가
+    // 계속 검색에 나왔다(advisor beta 발견 2, hybridSearch 로 실측 재현).
+    // 그래서 "모든 관찰 변경은 mutateEntityAndInvalidate 를 통한다"는 규칙에
+    // 예외가 하나 있었고, 그 예외가 정확히 그 규칙이 막으려던 결함을 만들었다.
+    invalidateDerivedForEntity(entityId) {
+        const meta = this.db.prepare(`SELECT rowid FROM entity_embedding_metadata WHERE entity_id = ?`)
+            .get(entityId);
+        if (meta) {
+            this.db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${Number(meta.rowid)}`);
+            this.db.prepare(`DELETE FROM entity_embedding_metadata WHERE entity_id = ?`).run(entityId);
+        }
+        deleteStaleKgChunks(this.db, entityId);
+    }
+    // §6a-1 invariant: when an entity's embedding input changed but re-embedding
+    // is unavailable, its old vector must not stay searchable.
+    invalidateEntityVector(entityId) {
+        if (!this.db)
+            return;
+        const meta = this.db.prepare(`SELECT rowid FROM entity_embedding_metadata WHERE entity_id = ?`)
+            .get(entityId);
+        if (!meta)
+            return;
+        const tx = this.db.transaction(() => {
+            this.db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${Number(meta.rowid)}`);
+            this.db.prepare(`DELETE FROM entity_embedding_metadata WHERE entity_id = ?`).run(entityId);
+        });
+        tx();
+        this.coordinator?.invalidateCoverage();
+    }
+    // Backfill callback: re-embed one chunk and commit vector + provenance in a
+    // single transaction (§6a-2).
+    async reembedChunkByRowid(rowid) {
+        if (!this.db)
+            return false;
+        const row = this.db.prepare(`SELECT text FROM chunk_metadata WHERE rowid = ?`)
+            .get(rowid);
+        if (!row || row.text === null)
+            return false;
+        try {
+            const embedding = await this.generateEmbedding(row.text, 1024, false, 'backfill');
+            const hash = createHash('sha256').update(row.text).digest('hex');
+            const safe = Number(rowid);
+            // Write-back CAS (beta 2R B1): the rowid may have been deleted and reused
+            // by a re-sync while inference ran — re-read the CURRENT text in the
+            // transaction and only write when it still matches what was embedded.
+            const tx = this.db.transaction(() => {
+                const cur = this.db.prepare(`SELECT text FROM chunk_metadata WHERE rowid = ?`).get(rowid);
+                if (!cur || cur.text !== row.text)
+                    return false; // superseded — discard
+                this.db.exec(`DELETE FROM chunks WHERE rowid = ${safe}`);
+                this.db.prepare(`INSERT INTO chunks (rowid, embedding) VALUES (${safe}, ?)`).run(Buffer.from(embedding.buffer));
+                this.db.prepare(`UPDATE chunk_metadata SET input_hash = ?, profile_id = ?, provenance_state = 'verified' WHERE rowid = ?`)
+                    .run(hash, this.currentProfileId, rowid);
+                this.db.prepare(`DELETE FROM embedding_backfill_failures WHERE kind = 'chunk' AND target_id = ?`).run(String(rowid));
+                return true;
+            });
+            const written = tx();
+            this.coordinator?.invalidateCoverage();
+            return written;
+        }
+        catch (e) {
+            if (e instanceof GateNotReadyError || e instanceof GateDisabledError)
+                return false;
+            throw e;
+        }
+    }
+    // spec §3 shutdown order (beta B1): block new batches -> settle coordinator
+    // (INCLUDING an in-flight reconciliation pass) -> settle gate (INCLUDING an
+    // in-flight model load, bounded) -> close DB -> natural exit.
+    //
+    // Bounded-exit rationale, re-derived after beta 1R: the exit decision is made
+    // AFTER the settle wait, not before — if the load completed during settling
+    // (ONNX session now exists) we take the natural-exit path. Only when the load
+    // is STILL pending after the deadline (dominant case: the 1.2GB download,
+    // which is un-abortable through transformers.js and would hold the event
+    // loop indefinitely) do we exit(). At that point the DB is already closed
+    // cleanly, so even the residual worst case — the load being inside ONNX
+    // session construction at exit — risks an ugly abort message, never data
+    // loss. Hanging forever is the alternative and is worse.
+    async shutdownAll() {
+        console.error('\n🧹 Cleaning up...');
+        try {
+            await this.coordinator?.shutdown(5000);
+        }
+        catch { /* settle best-effort */ }
+        try {
+            await this.gate?.shutdown(5000);
+        }
+        catch { /* settle best-effort */ }
+        const loadStillPending = this.gate?.loadInFlight ?? false;
+        try {
+            this.cleanup();
+        }
+        catch { /* DB close */ }
+        process.exitCode = process.exitCode ?? 0;
+        if (loadStillPending) {
+            console.error('… model load/download still in flight after settle deadline — bounded exit (DB already closed)');
+            process.exit(process.exitCode);
         }
     }
     async runMigrations() {
@@ -123,6 +487,11 @@ export class RAGKnowledgeGraphManager {
         });
         // Get pending migrations before running them
         const pendingBefore = migrationManager.getPendingMigrations();
+        // spec §5.1: 대기 중 마이그레이션이 있으면 먼저 일관 스냅샷을 남긴다.
+        // 실패는 throw = fail-closed (백업 없이 스키마를 바꾸지 않는다).
+        // await: 백업은 Online Backup API 를 쓰므로 비동기다. 여기서 await 를 빠뜨리면
+        // 백업이 끝나기 전에 마이그레이션이 시작한다 = 백업 없이 스키마를 바꾸는 것이다.
+        await backupBeforeMigration(this.db, DB_FILE_PATH, pendingBefore.map(m => m.version), migrationManager.getCurrentVersion());
         // Run pending migrations
         const result = await migrationManager.runMigrations();
         console.error(`🔧 Database schema ready (version ${result.currentVersion}, ${result.applied} migrations applied)`);
@@ -140,11 +509,6 @@ export class RAGKnowledgeGraphManager {
             this.encoding.free();
             this.encoding = null;
         }
-        if (this.embeddingModel) {
-            // Clean up the embedding model if it has cleanup methods
-            this.embeddingModel = null;
-            this.modelInitialized = false;
-        }
         this.embeddingCache.clear();
         if (this.db) {
             this.db.close();
@@ -163,42 +527,73 @@ export class RAGKnowledgeGraphManager {
         if (!this.db)
             throw new Error('Database not initialized');
         const result = [];
+        // v13: 관찰은 lifecycle 테이블이 정본이고 entities.observations 는 projection 이다.
+        // entity 행은 빈 배열로 만들고 rebuildProjection 이 채운다.
         const insertStmt = this.db.prepare(`
       INSERT OR IGNORE INTO entities (id, name, entityType, observations, metadata)
-      VALUES (?, ?, ?, ?, ?)
+      VALUES (?, ?, ?, '[]', ?)
     `);
+        const stripDate = (s2) => s2.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
         for (const entity of entities) {
             const entityId = `entity_${entity.name.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
-            const timestamped = (entity.observations || []).map(o => this._timestampObservation(o));
-            // Try insert first
-            const insertResult = insertStmt.run(entityId, entity.name, entity.entityType, JSON.stringify(timestamped), '{}');
-            if (insertResult.changes > 0) {
-                // New entity created
-                result.push({ ...entity, observations: timestamped });
-                console.error(`🔮 Generating embedding for new entity: ${entity.name}`);
-                await this.embedEntity(entityId);
-            }
-            else {
-                // Entity already exists — upsert: merge observations and update entityType
-                const existing = this.db.prepare(`SELECT observations, entityType FROM entities WHERE id = ?`)
-                    .get(entityId);
-                if (existing) {
-                    const currentObs = JSON.parse(existing.observations);
-                    // Strip date prefix for dedup comparison
-                    const stripDate = (s) => s.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
-                    const currentBare = new Set(currentObs.map(stripDate));
-                    const newObs = timestamped.filter(o => !currentBare.has(stripDate(o)));
-                    const needsTypeUpdate = entity.entityType && entity.entityType !== 'CONCEPT' && entity.entityType !== existing.entityType;
-                    if (newObs.length > 0 || needsTypeUpdate) {
-                        const mergedObs = [...currentObs, ...newObs];
-                        const updatedType = needsTypeUpdate ? entity.entityType : existing.entityType;
-                        this.db.prepare(`UPDATE entities SET observations = ?, entityType = ? WHERE id = ?`)
-                            .run(JSON.stringify(mergedObs), updatedType, entityId);
-                        console.error(`♻️ Upserted entity: ${entity.name} (+${newObs.length} obs${needsTypeUpdate ? ', type→' + updatedType : ''})`);
-                        await this.embedEntity(entityId);
-                        result.push({ ...entity, observations: mergedObs });
+            const ts = new Date().toISOString();
+            const ids = [];
+            let created = false;
+            let addedCount = 0;
+            let typeUpdated = false;
+            // entity INSERT 도 같은 트랜잭션 안이다. 밖에 두면 lifecycle INSERT 가
+            // 실패할 때 entity 행만 남는 split state 가 생긴다
+            // (advisor 구현리뷰 r1 발견 2, 실행 재현).
+            const changed = this.mutateEntityAndInvalidate(entityId, () => {
+                created = insertStmt.run(entityId, entity.name, entity.entityType, '{}').changes > 0;
+                if (!created && entity.entityType && entity.entityType !== 'CONCEPT') {
+                    const cur = this.db.prepare(`SELECT entityType FROM entities WHERE id = ?`)
+                        .get(entityId);
+                    if (cur && cur.entityType !== entity.entityType) {
+                        this.db.prepare(`UPDATE entities SET entityType = ? WHERE id = ?`)
+                            .run(entity.entityType, entityId);
+                        typeUpdated = true;
                     }
                 }
+                const activeRows = this.db.prepare(`SELECT observation_id, content FROM entity_observations
+           WHERE entity_id = ? AND status = 'active'`).all(entityId);
+                const activeByBare = new Map(activeRows.map(r => [stripDate(r.content), r.observation_id]));
+                let sourcesAdded = 0;
+                for (const raw of (entity.observations || [])) {
+                    const content = this._timestampObservation(raw);
+                    const bare = stripDate(content);
+                    const dupId = activeByBare.get(bare);
+                    if (dupId) {
+                        // 같은 사실이 다른 출처에서 다시 왔다 = evidence 추가, 새 revision 아님.
+                        if (entity.sources?.length)
+                            sourcesAdded += linkSources(this.db, dupId, entity.sources, ts);
+                        ids.push(null);
+                        continue;
+                    }
+                    const id = addRevision(this.db, {
+                        entityId, content, status: entity.status ?? 'active', sources: entity.sources, ts
+                    });
+                    activeByBare.set(bare, id);
+                    ids.push(id);
+                    addedCount++;
+                }
+                // 아무것도 안 바뀌었으면 projection·벡터·KG 를 건드리지 않는다.
+                return created || typeUpdated || addedCount > 0 || sourcesAdded > 0;
+            });
+            const projected = JSON.parse(this.db.prepare(`SELECT observations FROM entities WHERE id = ?`)
+                .get(entityId).observations);
+            // 재임베딩은 무효화가 실제로 일어났을 때만. 조건이 갈리면
+            // "벡터를 지우고 다시 만들지 않는" 창이 생긴다.
+            if (changed) {
+                console.error(created
+                    ? `🔮 Generating embedding for new entity: ${entity.name}`
+                    : `♻️ Upserted entity: ${entity.name} (+${addedCount} obs${typeUpdated ? ', type→' + entity.entityType : ''})`);
+                const embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
+                result.push({ ...entity, observations: projected, created,
+                    observation_ids: ids, embedding_status });
+            }
+            else {
+                result.push({ ...entity, observations: projected, created, observation_ids: ids });
             }
         }
         return result;
@@ -208,24 +603,32 @@ export class RAGKnowledgeGraphManager {
             throw new Error('Database not initialized');
         const newRelations = [];
         for (const relation of relations) {
-            // Ensure entities exist
-            await this.createEntities([
+            // Ensure entities exist. v3.6 (spec §5c): auto-created endpoints may be
+            // embedded/queued/disabled independently — report per endpoint; 'n/a'
+            // means the endpoint already existed (no embedding work happened here).
+            const ensured = await this.createEntities([
                 { name: relation.from, entityType: 'CONCEPT', observations: [] },
                 { name: relation.to, entityType: 'CONCEPT', observations: [] }
             ]);
+            const statusOf = (name) => {
+                const hit = ensured.find(e => e.name === name);
+                return hit?.embedding_status ?? 'n/a';
+            };
+            const endpoint_embedding_status = { from: statusOf(relation.from), to: statusOf(relation.to) };
             const sourceId = `entity_${relation.from.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
             const targetId = `entity_${relation.to.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
             const relationId = `rel_${sourceId}_${relation.relationType}_${targetId}`.toLowerCase();
             const stmt = this.db.prepare(`
-        INSERT OR IGNORE INTO relationships 
+        INSERT OR IGNORE INTO relationships
         (id, source_entity, target_entity, relationType, confidence, metadata)
         VALUES (?, ?, ?, ?, ?, ?)
       `);
             const result = stmt.run(relationId, sourceId, targetId, relation.relationType, 1.0, '{}');
             if (result.changes > 0) {
-                newRelations.push(relation);
+                newRelations.push({ ...relation, endpoint_embedding_status });
             }
         }
+        this.coordinator?.kick();
         return newRelations;
     }
     async addObservations(observations) {
@@ -234,31 +637,144 @@ export class RAGKnowledgeGraphManager {
         const results = [];
         for (const obs of observations) {
             const entityId = `entity_${obs.entityName.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
-            // Get current observations
-            const entity = this.db.prepare(`
-        SELECT observations FROM entities WHERE id = ?
-      `).get(entityId);
-            if (!entity) {
+            const entity = this.db.prepare(`SELECT id FROM entities WHERE id = ?`).get(entityId);
+            if (!entity)
                 throw new Error(`Entity with name ${obs.entityName} not found`);
-            }
-            const currentObservations = JSON.parse(entity.observations);
-            const stripDate = (s) => s.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
-            const currentBare = new Set(currentObservations.map(stripDate));
-            const timestamped = obs.contents.map(c => this._timestampObservation(c));
-            const newObservations = timestamped.filter(c => !currentBare.has(stripDate(c)));
-            if (newObservations.length > 0) {
-                const updatedObservations = [...currentObservations, ...newObservations];
-                this.db.prepare(`
-          UPDATE entities SET observations = ? WHERE id = ?
-        `).run(JSON.stringify(updatedObservations), entityId);
-                // Regenerate embedding for the updated entity
+            // dedup 기준은 v3.6 과 같다: 날짜 prefix 를 뗀 본문이 active 에 이미 있으면
+            // 새 revision 을 만들지 않는다. 다만 v13 에서는 같은 사실이 다른 출처에서 다시
+            // 온 것이므로 그 revision 에 source link 를 더한다(spec §8.3 T13).
+            const stripDate = (s2) => s2.replace(/^\[\d{4}-\d{2}-\d{2}\]\s*/, '');
+            const activeRows = this.db.prepare(`SELECT observation_id, content FROM entity_observations
+         WHERE entity_id = ? AND status = 'active'`).all(entityId);
+            const activeByBare = new Map(activeRows.map(r => [stripDate(r.content), r.observation_id]));
+            const ts = new Date().toISOString();
+            const ids = [];
+            const added = [];
+            let sourcesAdded = 0;
+            const changed = this.mutateEntityAndInvalidate(entityId, () => {
+                for (const raw of obs.contents) {
+                    const content = this._timestampObservation(raw);
+                    const bare = stripDate(content);
+                    const dupId = activeByBare.get(bare);
+                    if (dupId) {
+                        if (obs.sources?.length)
+                            sourcesAdded += linkSources(this.db, dupId, obs.sources, ts);
+                        ids.push(null);
+                        continue;
+                    }
+                    const id = addRevision(this.db, {
+                        entityId, content, status: obs.status ?? 'active', sources: obs.sources, ts
+                    });
+                    activeByBare.set(bare, id);
+                    ids.push(id);
+                    added.push(content);
+                }
+                // 아무것도 안 바뀌었으면 projection·벡터·KG 를 건드리지 않는다.
+                // 이 반환이 없으면 빈 contents 나 dedup-only add 가 정상 벡터를
+                // 지우고 재임베딩도 안 한다(advisor 구현리뷰 r1 발견 1).
+                return added.length > 0 || sourcesAdded > 0;
+            });
+            let embedding_status;
+            if (changed) {
                 console.error(`🔮 Regenerating embedding for updated entity: ${obs.entityName}`);
-                await this.embedEntity(entityId);
+                embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
             }
-            results.push({ entityName: obs.entityName, addedObservations: newObservations });
+            results.push({ entityName: obs.entityName, observation_ids: ids,
+                addedObservations: added, embedding_status });
         }
         return results;
     }
+    async correctObservation(observationId, content, changeKind = 'correction', reason) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const row = this.db.prepare(`SELECT entity_id FROM entity_observations WHERE observation_id = ?`)
+            .get(observationId);
+        if (!row)
+            throw new Error(`observation ${observationId} not found`);
+        let newId = '';
+        const ts = new Date().toISOString();
+        this.mutateEntityAndInvalidate(row.entity_id, () => {
+            newId = correctRevision(this.db, {
+                observationId, content: this._timestampObservation(content),
+                changeKind, reason: reason ?? null, ts
+            });
+        });
+        await this.tryEmbedEntity(row.entity_id, 'bulk');
+        return newId;
+    }
+    async _transition(observationId, event, reason) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        const row = this.db.prepare(`SELECT entity_id FROM entity_observations WHERE observation_id = ?`)
+            .get(observationId);
+        if (!row)
+            throw new Error(`observation ${observationId} not found`);
+        const ts = new Date().toISOString();
+        this.mutateEntityAndInvalidate(row.entity_id, () => {
+            transitionStatus(this.db, { observationId, event, reason: reason ?? null, ts });
+        });
+        await this.tryEmbedEntity(row.entity_id, 'bulk');
+    }
+    async retractObservation(observationId, reason) {
+        return this._transition(observationId, 'retract', reason);
+    }
+    async restoreObservation(observationId, reason) {
+        return this._transition(observationId, 'restore', reason);
+    }
+    async approveObservation(observationId, reason) {
+        return this._transition(observationId, 'approve', reason);
+    }
+    async declineObservation(observationId, reason) {
+        return this._transition(observationId, 'decline', reason);
+    }
+    // DESTRUCTIVE. Physically removes revisions (and their sources via CASCADE).
+    //
+    // Chain contract (advisor 구현리뷰 r1 발견 4): a revision chain is
+    // rev1 <- rev2 <- ... and purging a middle revision would either fail on the
+    // supersedes_id FK or leave a chain pointing at a deleted row, plus events
+    // whose from_id/to_id dangle. So purge is defined as **suffix purge from the
+    // target to the newest revision of that root**, newest-first:
+    //   - purging the newest revision removes exactly it
+    //   - purging rev2 of a 3-revision chain removes rev3 then rev2
+    //   - purging rev1 removes the whole chain
+    // Events for purged revisions are removed too, so no event dangles.
+    // The root row is always kept: its projection_order stays reserved, because
+    // reusing an order would make a later restore/approve fail on the
+    // active-order index.
+    async purgeObservation(observationId, confirm) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        if (confirm !== 'PURGE') {
+            throw new Error(`purgeObservation refused: pass confirm='PURGE' to physically delete a revision. ` +
+                `This destroys history — retractObservation() is almost always what you want.`);
+        }
+        const row = this.db.prepare(`SELECT entity_id, root_id, revision_no FROM entity_observations WHERE observation_id = ?`)
+            .get(observationId);
+        if (!row)
+            return { purged: 0 };
+        let purged = 0;
+        this.mutateEntityAndInvalidate(row.entity_id, () => {
+            // newest-first so each DELETE has no successor referencing it
+            const victims = this.db.prepare(`SELECT observation_id FROM entity_observations
+         WHERE root_id = ? AND revision_no >= ?
+         ORDER BY revision_no DESC`).all(row.root_id, row.revision_no);
+            for (const v of victims) {
+                this.db.prepare(`DELETE FROM observation_events WHERE from_id = ? OR to_id = ?`)
+                    .run(v.observation_id, v.observation_id);
+                purged += this.db.prepare(`DELETE FROM entity_observations WHERE observation_id = ?`)
+                    .run(v.observation_id).changes;
+            }
+            return purged > 0;
+        });
+        await this.tryEmbedEntity(row.entity_id, 'bulk');
+        return { purged };
+    }
+    // spec §6.2: 과거 판본은 여기서만 나온다. 일반 검색은 active 만 반환한다.
+    async getObservationHistory(sel) {
+        if (!this.db)
+            throw new Error('Database not initialized');
+        return getObservationHistory(this.db, sel);
+    }
     async deleteEntities(entityNames) {
         if (!this.db)
             throw new Error('Database not initialized');
@@ -322,22 +838,91 @@ export class RAGKnowledgeGraphManager {
         }
         console.error(`✅ Entity deletion process completed`);
     }
+    // v3.6 (spec §5c, breaking): structured per-entity results + re-embedding.
+    // Pre-3.6 this method silently left STALE entity vectors behind (the input
+    // text changed but the vector was never regenerated) — fixed via
+    // tryEmbedEntity, which also covers the not-ready dirty contract.
+    // DEPRECATED shim (v13, one version only). Content-addressed deletion cannot
+    // express "which revision" — use retractObservation(observation_id) instead.
+    // Semantics: exact-string match against ACTIVE revisions -> soft retract.
+    //
+    // The whole call is one transaction and ambiguity is judged before any
+    // mutation: if any item matches 2+ active revisions the call aborts with 0
+    // mutations (spec §6.3). That is a deliberate change from v3.6, which deleted
+    // every duplicate and carried on — a machine cannot pick which revision was meant.
+    //
+    // Duplicate ids across items are collapsed. Without that, listing the same
+    // (entity, content) twice retracted it once and then failed on an illegal
+    // transition, returning an error *after* committing part of the batch
+    // (advisor 구현리뷰 r1 발견 3, 실행 재현). Embedding runs after the commit.
     async deleteObservations(deletions) {
         if (!this.db)
             throw new Error('Database not initialized');
-        for (const deletion of deletions) {
-            const entityId = `entity_${deletion.entityName.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
-            const entity = this.db.prepare(`
-        SELECT observations FROM entities WHERE id = ?
-      `).get(entityId);
-            if (entity) {
-                const currentObservations = JSON.parse(entity.observations);
-                const filteredObservations = currentObservations.filter((obs) => !deletion.observations.includes(obs));
-                this.db.prepare(`
-          UPDATE entities SET observations = ? WHERE id = ?
-        `).run(JSON.stringify(filteredObservations), entityId);
+        const plan = [];
+        const ambiguous = [];
+        const claimed = new Set(); // 항목 간 중복 id 흡수
+        for (const d of deletions) {
+            const entityId = `entity_${d.entityName.toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
+            const ids = [];
+            for (const content of d.observations) {
+                const rows = this.db.prepare(`SELECT observation_id FROM entity_observations
+           WHERE entity_id = ? AND status = 'active' AND content = ?`).all(entityId, content);
+                if (rows.length > 1) {
+                    ambiguous.push({ entityName: d.entityName, content, matches: rows.length });
+                    continue;
+                }
+                if (rows.length === 1 && !claimed.has(rows[0].observation_id)) {
+                    claimed.add(rows[0].observation_id);
+                    ids.push(rows[0].observation_id);
+                }
+                // rows.length === 0 -> no-op (v3.6 behaviour, spec §6.3-3)
+            }
+            plan.push({ entityName: d.entityName, entityId, ids });
+        }
+        if (ambiguous.length > 0) {
+            throw new Error(`AMBIGUOUS_OBSERVATION_MATCH: ${ambiguous.length} item(s) matched multiple active ` +
+                `revisions; 0 mutations were applied. Use retractObservation(observation_id) instead. ` +
+                `Conflicts: ${JSON.stringify(ambiguous)}`);
+        }
+        // pass 2 — mutate everything in ONE transaction so a failure anywhere
+        // leaves zero mutations. Per-plan transactions plus an awaited embedding
+        // in between made a partial commit observable.
+        const touched = plan.filter(p => p.ids.length > 0);
+        const ts = new Date().toISOString();
+        if (touched.length > 0) {
+            const tx = this.db.transaction(() => {
+                for (const p of touched) {
+                    for (const id of p.ids) {
+                        transitionStatus(this.db, { observationId: id, event: 'retract',
+                            reason: 'deleteObservations (deprecated shim)', ts });
+                    }
+                    rebuildProjection(this.db, p.entityId);
+                    const meta = this.db.prepare(`SELECT rowid FROM entity_embedding_metadata WHERE entity_id = ?`)
+                        .get(p.entityId);
+                    if (meta) {
+                        this.db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${Number(meta.rowid)}`);
+                        this.db.prepare(`DELETE FROM entity_embedding_metadata WHERE entity_id = ?`)
+                            .run(p.entityId);
+                    }
+                    deleteStaleKgChunks(this.db, p.entityId);
+                }
+            });
+            tx();
+            this.coordinator?.invalidateCoverage();
+        }
+        // pass 3 — embedding after the commit
+        const results = [];
+        let total = 0;
+        for (const p of plan) {
+            if (p.ids.length === 0) {
+                results.push({ entityName: p.entityName, deleted: 0, embedding_status: 'n/a' });
+                continue;
             }
+            const embedding_status = await this.tryEmbedEntity(p.entityId, 'bulk');
+            results.push({ entityName: p.entityName, deleted: p.ids.length, embedding_status });
+            total += p.ids.length;
         }
+        return { results, total_deleted: total };
     }
     async deleteRelations(relations) {
         if (!this.db)
@@ -524,10 +1109,24 @@ export class RAGKnowledgeGraphManager {
         console.error(`✅ getNeighbors: Found ${entities.length} entities, ${relations.length} relations, ${paths.length} paths (depth=${effectiveDepth})`);
         return { entities, relations, paths };
     }
+    // v3.6 (spec §5·§5c, additive): FTS lexical fallback when vector search is
+    // not eligible, hybrid-partial merge while backfill is catching up, and
+    // top-level state fields on every response.
     async searchNodes(query, limit = 10, since, until) {
         if (!this.db)
             throw new Error('Database not initialized');
         console.error(`🔍 Semantic entity search: "${query}"`);
+        const covS = this.coordinator?.coverage();
+        const entityPct = covS && covS.entity.total > 0 ? Math.round((covS.entity.embedded / covS.entity.total) * 100) : 100;
+        const stateFields = () => ({
+            model_state: this.gate.status.state,
+            coverage: { entity_pct: entityPct },
+        });
+        if (!(this.coordinator?.eligible ?? false)) {
+            // No waiting on the model (spec §5) — lexical entities_fts fallback.
+            return { ...this.searchNodesFts(query, limit, since, until), search_mode: 'fts-only',
+                ...stateFields(), degradation_reason: this.degradationReason() };
+        }
         const queryVariants = this.buildCrossLingualVariants(query);
         if (queryVariants.length > 1) {
             console.error(`🌐 searchNodes variants: ${queryVariants.slice(1).join(' | ')}`);
@@ -551,16 +1150,26 @@ export class RAGKnowledgeGraphManager {
       `).all(Buffer.from(embedding.buffer), k);
         };
         const resultMap = new Map();
-        for (const variant of queryVariants) {
-            const embedding = await this.generateEmbedding(variant, 1024, true);
-            const variantResults = searchEntities(embedding, limit * 2);
-            for (const result of variantResults) {
-                const existing = resultMap.get(result.entity_id);
-                if (!existing || result.distance < existing.distance) {
-                    resultMap.set(result.entity_id, result);
+        try {
+            for (const variant of queryVariants) {
+                const embedding = await this.generateEmbedding(variant, 1024, true);
+                const variantResults = searchEntities(embedding, limit * 2);
+                for (const result of variantResults) {
+                    const existing = resultMap.get(result.entity_id);
+                    if (!existing || result.distance < existing.distance) {
+                        resultMap.set(result.entity_id, result);
+                    }
                 }
             }
         }
+        catch (embErr) {
+            // Ready-state inference failure degrades to FTS instead of failing the
+            // tool (beta B6) — same contract as hybridSearch. The gate's own
+            // consecutive-failure counter handles the systemic transition.
+            console.error(`⚠️ searchNodes vector path failed — FTS fallback:`, embErr instanceof Error ? embErr.message : embErr);
+            return { ...this.searchNodesFts(query, limit, since, until), search_mode: 'fts-only',
+                ...stateFields(), degradation_reason: this.degradationReason() ?? 'inference_error' };
+        }
         const entityResults = Array.from(resultMap.values()).sort((a, b) => a.distance - b.distance).slice(0, limit);
         // Filter by temporal range if specified
         let filteredResults = entityResults;
@@ -576,35 +1185,79 @@ export class RAGKnowledgeGraphManager {
                 return true;
             });
         }
-        if (filteredResults.length === 0) {
-            console.error(`ℹ️ No semantic matches found for "${query}"`);
-            return { entities: [], relations: [] };
-        }
         const entities = filteredResults.map(result => ({
             name: result.name,
             entityType: result.entityType,
             observations: JSON.parse(result.observations),
             similarity: Math.max(0, 1 - result.distance / 2) // Convert cosine distance (0-2) to similarity (1-0)
         }));
-        // Get relationships between the found entities
-        const entityNames = entities.map(e => e.name);
-        const relations = this.db.prepare(`
-      SELECT 
+        // hybrid-partial (spec §4): entities without vectors must not vanish from
+        // search while backfill catches up — merge lexical FTS hits for the gap.
+        let search_mode = 'hybrid';
+        if (entityPct < 100) {
+            search_mode = 'hybrid-partial';
+            const seen = new Set(entities.map(e => e.name));
+            const ftsExtra = this.searchNodesFts(query, limit, since, until);
+            for (const e of ftsExtra.entities) {
+                if (entities.length >= limit)
+                    break;
+                if (!seen.has(e.name)) {
+                    seen.add(e.name);
+                    entities.push(e);
+                }
+            }
+        }
+        if (entities.length === 0) {
+            console.error(`ℹ️ No semantic matches found for "${query}"`);
+            return { entities: [], relations: [], search_mode, ...stateFields() };
+        }
+        const relations = this.relationsAmong(entities.map(e => e.name));
+        console.error(`✅ Found ${entities.length} semantically similar entities with ${relations.length} relationships`);
+        return { entities, relations, search_mode, ...stateFields() };
+    }
+    // Lexical entity search over entities_fts (spec §5 contract: name /
+    // observations / entityType lexical match — no semantic-equivalence claim).
+    // Temporal filters apply in SQL so LIMIT is not distorted.
+    searchNodesFts(query, limit, since, until) {
+        const expr = compileFtsLiteralQuery(query);
+        if (expr === null) {
+            return { entities: [], relations: [], warning: 'query has no searchable terms' };
+        }
+        const rows = this.db.prepare(`
+      SELECT e.name, e.entityType, e.observations
+      FROM entities_fts f
+      JOIN entities e ON f.rowid = e.rowid
+      WHERE entities_fts MATCH @expr
+        ${since ? 'AND e.created_at >= @since' : ''}
+        ${until ? 'AND e.created_at <= @until' : ''}
+      ORDER BY bm25(entities_fts)
+      LIMIT @limit
+    `).all({ expr, since, until, limit });
+        const entities = rows.map(r => ({
+            name: r.name,
+            entityType: r.entityType,
+            observations: JSON.parse(r.observations),
+        }));
+        return { entities, relations: this.relationsAmong(entities.map(e => e.name)) };
+    }
+    relationsAmong(entityNames) {
+        if (entityNames.length === 0)
+            return [];
+        return this.db.prepare(`
+      SELECT
         e1.name as from_name,
         e2.name as to_name,
         r.relationType
       FROM relationships r
       JOIN entities e1 ON r.source_entity = e1.id
       JOIN entities e2 ON r.target_entity = e2.id
-      WHERE e1.name IN (${entityNames.map(() => '?').join(',')}) 
+      WHERE e1.name IN (${entityNames.map(() => '?').join(',')})
         AND e2.name IN (${entityNames.map(() => '?').join(',')})
     `).all(...entityNames, ...entityNames).map((row) => ({
             from: row.from_name,
             to: row.to_name,
             relationType: row.relationType
         }));
-        console.error(`✅ Found ${entities.length} semantically similar entities with ${relations.length} relationships`);
-        return { entities, relations };
     }
     async openNodes(names) {
         if (!this.db)
@@ -800,7 +1453,7 @@ export class RAGKnowledgeGraphManager {
         };
     }
     // Generate and store embedding for a single entity
-    async embedEntity(entityId) {
+    async embedEntity(entityId, priority = 'bulk') {
         if (!this.db)
             throw new Error('Database not initialized');
         // Get entity data
@@ -822,28 +1475,43 @@ export class RAGKnowledgeGraphManager {
         // char size (identity excluded), and embed duration. `capped` = some observation chars dropped.
         const capped = built.cappedObsChars < built.filteredObsChars;
         const embedStart = Date.now();
-        const embedding = await this.generateEmbedding(embeddingText);
+        const embedding = await this.generateEmbedding(embeddingText, 1024, false, priority);
         const embedMs = Date.now() - embedStart;
         console.error(`[embed] ${entity.name}: ${built.selectedObsCount}/${built.totalObsCount} obs, ${built.filteredObsChars}ch -> ${built.cappedObsChars}ch${capped ? ' (capped)' : ''}, ${embedMs}ms`);
         try {
-            // Delete existing embedding if any
-            const existingMetadata = this.db.prepare(`
-        SELECT rowid FROM entity_embedding_metadata WHERE entity_id = ?
-      `).get(entityId);
-            if (existingMetadata) {
-                this.db.prepare(`DELETE FROM entity_embeddings WHERE rowid = ?`).run(existingMetadata.rowid);
-                this.db.prepare(`DELETE FROM entity_embedding_metadata WHERE entity_id = ?`).run(entityId);
+            // v3.6 (§6a-2): vector replace + provenance stamp commit atomically.
+            // Write-back CAS (beta 2R B1): the entity may have been mutated again
+            // while THIS inference was in flight — a late writer must never
+            // re-insert a vector for superseded content as 'verified'. Inside the
+            // write transaction the CURRENT entity text is rebuilt and hashed; on
+            // mismatch the result is discarded and the row stays missing/queued for
+            // the backfill pass that the newer mutation already kicked.
+            const inputHash = this.hashWithBuilderVersion(embeddingText);
+            const writeTx = this.db.transaction(() => {
+                const currentHash = this.entityInputHash(entityId);
+                if (currentHash !== inputHash)
+                    return false; // superseded — discard
+                const existingMetadata = this.db.prepare(`
+          SELECT rowid FROM entity_embedding_metadata WHERE entity_id = ?
+        `).get(entityId);
+                if (existingMetadata) {
+                    this.db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${Number(existingMetadata.rowid)}`);
+                    this.db.prepare(`DELETE FROM entity_embedding_metadata WHERE entity_id = ?`).run(entityId);
+                }
+                const result = this.db.prepare(`
+          INSERT INTO entity_embeddings (embedding) VALUES (?)
+        `).run(Buffer.from(embedding.buffer));
+                this.db.prepare(`
+          INSERT INTO entity_embedding_metadata (rowid, entity_id, embedding_text, input_hash, profile_id, provenance_state)
+          VALUES (?, ?, ?, ?, ?, 'verified')
+        `).run(result.lastInsertRowid, entityId, embeddingText, inputHash, this.currentProfileId);
+                return true;
+            });
+            const written = writeTx();
+            if (!written) {
+                console.error(`⏭️ discarded superseded embedding for ${entityId} (entity changed during inference)`);
             }
-            // Insert new embedding
-            const result = this.db.prepare(`
-        INSERT INTO entity_embeddings (embedding) VALUES (?)
-      `).run(Buffer.from(embedding.buffer));
-            // Store metadata
-            this.db.prepare(`
-        INSERT INTO entity_embedding_metadata (rowid, entity_id, embedding_text)
-        VALUES (?, ?, ?)
-      `).run(result.lastInsertRowid, entityId, embeddingText);
-            return true;
+            return written;
         }
         catch (error) {
             console.error(`Failed to embed entity ${entityId}:`, error);
@@ -866,6 +1534,7 @@ export class RAGKnowledgeGraphManager {
             embeddedCount += results.filter(Boolean).length;
         }
         console.error(`✅ Entity embeddings completed: ${embeddedCount}/${entities.length} entities embedded`);
+        this.coordinator?.invalidateCoverage();
         return {
             totalEntities: entities.length,
             embeddedEntities: embeddedCount
@@ -945,15 +1614,20 @@ export class RAGKnowledgeGraphManager {
         const errors = [];
         for (const chunk of chunks) {
             // Generate embedding
-            const embedding = await this.generateEmbedding(chunk.text);
+            const embedding = await this.generateEmbedding(chunk.text, 1024, false, 'bulk');
             const rowid = safeRowid(chunk.rowid);
             try {
-                // Delete existing embedding if any
-                this.db.exec(`DELETE FROM chunks WHERE rowid = ${rowid}`);
-                // Insert new embedding - rowid as literal integer for vec0 compatibility
-                this.db.prepare(`
-          INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)
-        `).run(Buffer.from(embedding.buffer));
+                // vector + verified provenance in one transaction (§6a-2) — KG chunks
+                // must never become vector-bearing provenance-NULL rows post-recon.
+                const tx = this.db.transaction(() => {
+                    this.db.exec(`DELETE FROM chunks WHERE rowid = ${rowid}`);
+                    this.db.prepare(`
+            INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)
+          `).run(Buffer.from(embedding.buffer));
+                    this.db.prepare(`UPDATE chunk_metadata SET input_hash = ?, profile_id = ?, provenance_state = 'verified' WHERE rowid = ?`)
+                        .run(createHash('sha256').update(chunk.text).digest('hex'), this.currentProfileId, chunk.rowid);
+                });
+                tx();
                 embeddedCount++;
             }
             catch (error) {
@@ -962,6 +1636,7 @@ export class RAGKnowledgeGraphManager {
                 errors.push(errMsg);
             }
         }
+        this.coordinator?.invalidateCoverage();
         console.error(`✅ Knowledge graph chunks embedded: ${embeddedCount}/${chunks.length}`);
         return { embeddedChunks: embeddedCount, totalChunks: chunks.length, ...(errors.length > 0 && { errors: errors.slice(0, 5) }) };
     }
@@ -1185,37 +1860,23 @@ export class RAGKnowledgeGraphManager {
     }
     // Generate embeddings using sentence transformers
     // isQuery: true for search queries (adds instruction prefix), false for documents/entities
-    async generateEmbedding(text, dimensions = 1024, isQuery = false) {
+    async generateEmbedding(text, dimensions = 1024, isQuery = false, priority = 'interactive') {
         // Check cache first (hash-based key to avoid collisions on long texts)
         const cacheKey = createHash('md5').update(`${text}_${dimensions}_${isQuery}`).digest('hex');
         const cached = this.embeddingCache.get(cacheKey);
         if (cached)
             return cached;
-        if (this.modelInitialized && this.embeddingModel) {
-            try {
-                // BGE-M3: instruction prefix improves retrieval quality for queries
-                const inputText = isQuery
-                    ? `Represent this sentence for searching relevant passages: ${text}`
-                    : text;
-                const result = await this.embeddingModel(inputText, { pooling: 'cls', normalize: true });
-                // Extract the embedding array and convert to Float32Array
-                const embedding = result.data;
-                const modelResult = new Float32Array(embedding.slice(0, dimensions));
-                // Cache the result (LRU: evict oldest if full)
-                if (this.embeddingCache.size >= this.EMBEDDING_CACHE_MAX) {
-                    const firstKey = this.embeddingCache.keys().next().value;
-                    if (firstKey)
-                        this.embeddingCache.delete(firstKey);
-                }
-                this.embeddingCache.set(cacheKey, modelResult);
-                return modelResult;
-            }
-            catch (error) {
-                console.error(`⚠️ Embedding model failed for text "${text.slice(0, 50)}...":`, error instanceof Error ? error.message : error);
-                throw new Error(`Embedding model not available. Ensure the model is loaded. Original error: ${error instanceof Error ? error.message : error}`);
-            }
-        }
-        throw new Error('Embedding model not initialized. The server may still be loading the model — retry in a few seconds.');
+        // v3.6: all inference goes through the gate — state check + execution in one
+        // atomic boundary (TOCTOU-safe). GateNotReadyError / GateDisabledError
+        // propagate so each consumer honors its own not-ready contract (spec §5).
+        const modelResult = await this.gate.embed(text, { dims: dimensions, isQuery, priority });
+        if (this.embeddingCache.size >= this.EMBEDDING_CACHE_MAX) {
+            const firstKey = this.embeddingCache.keys().next().value;
+            if (firstKey)
+                this.embeddingCache.delete(firstKey);
+        }
+        this.embeddingCache.set(cacheKey, modelResult);
+        return modelResult;
     }
     // === NEW SEPARATE TOOLS ===
     async syncDocumentFromFile(filePath, documentId, options = {}) {
@@ -1243,31 +1904,56 @@ export class RAGKnowledgeGraphManager {
             catch { /* ignore */ }
             if (existingHash === contentHash) {
                 const cmCount = this.db.prepare(`SELECT count(*) AS n FROM chunk_metadata WHERE document_id = ?`).get(documentId).n;
+                // "Embedded" for dedup completeness = vector exists AND its profile is
+                // current (or legacy-NULL awaiting grandfather). Raw vector counts
+                // would misjudge old-profile rows as complete (beta 1R supplement).
                 const embCount = this.db.prepare(`
-          SELECT count(*) AS n FROM chunks c JOIN chunk_metadata m ON c.rowid = m.rowid WHERE m.document_id = ?
+          SELECT count(*) AS n FROM chunks c JOIN chunk_metadata m ON c.rowid = m.rowid
+          WHERE m.document_id = ? AND (m.provenance_state IS NULL OR m.profile_id = ?)
+        `).get(documentId, this.currentProfileId).n;
+                const linked = this.db.prepare(`
+          SELECT count(DISTINCT ce.entity_id) AS n FROM chunk_entities ce
+          JOIN chunk_metadata m ON ce.chunk_rowid = m.rowid WHERE m.document_id = ?
         `).get(documentId).n;
                 if (cmCount > 0 && cmCount === embCount) {
-                    const linked = this.db.prepare(`
-            SELECT count(DISTINCT ce.entity_id) AS n FROM chunk_entities ce
-            JOIN chunk_metadata m ON ce.chunk_rowid = m.rowid WHERE m.document_id = ?
-          `).get(documentId).n;
                     console.error(`⏭️  syncDocumentFromFile: ${documentId} unchanged (hash match, ${cmCount} chunks embedded) — skipped`);
                     return { documentId, bytes, chunks: cmCount, embeddedChunks: embCount, linkedEntities: linked, skipped: true, reason: 'unchanged' };
                 }
+                if (cmCount > 0 && embCount < cmCount) {
+                    // v3.6 (spec §5b M12): identical content with incomplete/stale vectors
+                    // keeps the document, chunks, rowids and entity links — only the
+                    // missing vectors are re-queued via the coordinator. Full re-chunking
+                    // here would churn rowids and links for no content change.
+                    console.error(`♻️ syncDocumentFromFile: ${documentId} unchanged but ${cmCount - embCount} vectors missing — re-queued (chunks preserved)`);
+                    this.coordinator?.kick();
+                    return { documentId, bytes, chunks: cmCount, embeddedChunks: embCount, linkedEntities: linked, skipped: true, reason: 'unchanged-revectorizing', embedding_status: this.gate.isDisabled ? 'disabled' : 'queued' };
+                }
             }
         }
         console.error(`🔄 syncDocumentFromFile: ${documentId} <- ${filePath} (${bytes} bytes)`);
-        // 3. Pre-compute chunks + embeddings BEFORE any DB mutation. If embedding
-        //    throws (model down), the existing document is left completely intact.
+        // 3. Two contracts (spec §5b):
+        //    ready       — pre-compute ALL embeddings BEFORE any DB mutation; if
+        //                  inference throws mid-way the old document stays intact
+        //                  (v3.5.0 atomicity, unchanged).
+        //    not-ready   — intentional lazy sync: store document + chunks + FTS in
+        //                  one transaction with NO vectors (embedding_status:
+        //                  queued); the backfill coordinator recovers them.
         const { maxTokens = 800, overlap = 160 } = options.chunkParams || {};
         const segments = this.chunkText(content, maxTokens, overlap);
+        const lazySync = !this.gate.isReady;
         const embedded = [];
-        for (const seg of segments) {
-            const embedding = await this.generateEmbedding(seg.text);
-            embedded.push({ seg, embedding });
+        if (lazySync) {
+            for (const seg of segments)
+                embedded.push({ seg, embedding: null });
+        }
+        else {
+            for (const seg of segments) {
+                const embedding = await this.generateEmbedding(seg.text, 1024, false, 'bulk');
+                embedded.push({ seg, embedding });
+            }
         }
-        // 4. Atomic swap: delete old -> insert doc -> insert chunks + embeddings,
-        //    all in a single synchronous better-sqlite3 transaction (all-or-nothing).
+        // 4. Atomic swap: delete old -> insert doc -> insert chunks (+ embeddings
+        //    with verified provenance when ready), one synchronous transaction.
         const applyTx = this.db.transaction(() => {
             const db = this.db;
             // 4a. cleanup old doc (inlined sync version of cleanupDocument).
@@ -1281,7 +1967,8 @@ export class RAGKnowledgeGraphManager {
             // 4b. insert document.
             db.prepare(`INSERT INTO documents (id, content, metadata) VALUES (?, ?, ?)`)
                 .run(documentId, content, JSON.stringify(metadata));
-            // 4c. insert chunk_metadata (FTS5 chunks_fts auto-filled by trigger) + embeddings.
+            // 4c. insert chunk_metadata (FTS5 chunks_fts auto-filled by trigger);
+            //     vectors + provenance only on the ready path (§6a-2).
             for (const { seg, embedding } of embedded) {
                 const chunkId = `${documentId}_chunk_${seg.chunk_index}`;
                 const info = db.prepare(`
@@ -1289,11 +1976,18 @@ export class RAGKnowledgeGraphManager {
           VALUES (?, ?, ?, ?, ?, ?, ?, ?)
         `).run(chunkId, documentId, seg.chunk_index, seg.text, seg.start_pos, seg.end_pos, seg.start_token, seg.end_token);
                 const rowid = Number(info.lastInsertRowid);
-                db.prepare(`INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)`).run(Buffer.from(embedding.buffer));
+                if (embedding) {
+                    db.prepare(`INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)`).run(Buffer.from(embedding.buffer));
+                    db.prepare(`UPDATE chunk_metadata SET input_hash = ?, profile_id = ?, provenance_state = 'verified' WHERE rowid = ?`)
+                        .run(createHash('sha256').update(seg.text).digest('hex'), this.currentProfileId, rowid);
+                }
             }
         });
         applyTx();
-        const embeddedChunks = embedded.length;
+        this.coordinator?.invalidateCoverage();
+        if (lazySync)
+            this.coordinator?.kick();
+        const embeddedChunks = lazySync ? 0 : embedded.length;
         // 5. Entity linking AFTER commit. Non-destructive + idempotent (INSERT OR
         //    IGNORE), so a linking failure cannot corrupt the doc/embeddings.
         const linkedEntities = await this.autoLinkEntities(documentId);
@@ -1309,6 +2003,7 @@ export class RAGKnowledgeGraphManager {
             chunks: segments.length,
             embeddedChunks,
             linkedEntities,
+            embedding_status: lazySync ? (this.gate.isDisabled ? 'disabled' : 'queued') : 'embedded',
             ...(explicitlyLinked !== undefined ? { explicitlyLinked } : {}),
         };
         if (linkedEntities === 0 && explicitlyLinked === undefined) {
@@ -1366,6 +2061,10 @@ export class RAGKnowledgeGraphManager {
             });
         }
         console.error(`✅ Document chunked: ${chunks.length} chunks created`);
+        // Indirect missing-row producer (spec §5): freshly chunked rows have no
+        // vectors yet — let the coordinator recover them without a restart.
+        this.coordinator?.invalidateCoverage();
+        this.coordinator?.kick();
         return { documentId, chunks: resultChunks };
     }
     async embedChunks(documentId) {
@@ -1382,18 +2081,20 @@ export class RAGKnowledgeGraphManager {
         let embeddedCount = 0;
         const errors = [];
         for (const chunk of chunks) {
-            // Generate embedding
-            const embedding = await this.generateEmbedding(chunk.text);
+            // Generate embedding (foreground-bulk priority)
+            const embedding = await this.generateEmbedding(chunk.text, 1024, false, 'bulk');
             const rowid = Number(chunk.rowid);
-            // Store in vector table
+            // Store in vector table (+ verified provenance, §6a-2 atomic)
             try {
-                // First, delete any existing embedding for this rowid
-                this.db.exec(`DELETE FROM chunks WHERE rowid = ${safeRowid(rowid)}`);
-                // Insert new embedding with explicit rowid to match chunk_metadata
-                // Use parameterized only for embedding blob, rowid as literal integer
-                this.db.prepare(`
-          INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)
-        `).run(Buffer.from(embedding.buffer));
+                const tx = this.db.transaction(() => {
+                    this.db.exec(`DELETE FROM chunks WHERE rowid = ${safeRowid(rowid)}`);
+                    this.db.prepare(`
+            INSERT INTO chunks (rowid, embedding) VALUES (${rowid}, ?)
+          `).run(Buffer.from(embedding.buffer));
+                    this.db.prepare(`UPDATE chunk_metadata SET input_hash = ?, profile_id = ?, provenance_state = 'verified' WHERE rowid = ?`)
+                        .run(createHash('sha256').update(chunk.text).digest('hex'), this.currentProfileId, rowid);
+                });
+                tx();
                 embeddedCount++;
             }
             catch (error) {
@@ -1403,6 +2104,7 @@ export class RAGKnowledgeGraphManager {
             }
         }
         console.error(`✅ Chunks embedded: ${embeddedCount}/${chunks.length}`);
+        this.coordinator?.invalidateCoverage();
         // Auto-link entities to document after embedding
         const linkedCount = await this.autoLinkEntities(documentId);
         return { documentId, embeddedChunks: embeddedCount, totalChunks: chunks.length, linkedEntities: linkedCount, ...(errors.length > 0 && { errors: errors.slice(0, 5) }) };
@@ -1736,10 +2438,20 @@ export class RAGKnowledgeGraphManager {
             created_at: row.created_at
         }));
         console.error(`✅ Export completed: ${entities.length} entities, ${relations.length} relations, ${documents.length} documents`);
+        // spec §6.4: lifecycle 정본을 함께 내보낸다. 이게 없으면 export->import 뒤
+        // 관찰의 신원·출처·이력이 사라지고 projection 만 남는다.
+        const observation_roots = this.db.prepare(`SELECT * FROM observation_roots ORDER BY entity_id, projection_order`).all();
+        const entity_observations = this.db.prepare(`SELECT * FROM entity_observations ORDER BY root_id, revision_no`).all();
+        const observation_sources = this.db.prepare(`SELECT * FROM observation_sources ORDER BY observation_id, source_kind, source_ref`).all();
+        const observation_events = this.db.prepare(`SELECT * FROM observation_events ORDER BY root_id, recorded_at, event_id`).all();
         return {
             entities,
             relations,
             documents,
+            observation_roots,
+            entity_observations,
+            observation_sources,
+            observation_events,
             metadata: {
                 exportedAt: new Date().toISOString(),
                 version: PKG_VERSION,
@@ -1755,63 +2467,245 @@ export class RAGKnowledgeGraphManager {
         console.error(`📥 Importing knowledge graph (merge: ${options.merge !== false})...`);
         const imported = { entities: 0, relations: 0, documents: 0 };
         const skipped = { entities: 0, relations: 0, documents: 0 };
-        // If merge=false, clear existing data first
-        if (options.merge === false) {
-            this.db.exec(`DELETE FROM relationships`);
-            this.db.exec(`DELETE FROM entities`);
-            this.db.exec(`DELETE FROM documents`);
-            console.error('🗑️ Cleared existing data for full import');
-        }
-        // Import entities using INSERT OR IGNORE
-        if (data.entities && Array.isArray(data.entities)) {
-            const stmt = this.db.prepare(`
+        // merge 로 배열 위치가 재배정된 관찰. 조용히 순서를 바꾸면 호출자가 알 수 없으므로
+        // 응답으로 내보낸다(advisor beta r3 발견 3).
+        const remapReport = [];
+        // spec §6.4: abort 는 0 mutation 이다. lifecycle 만 트랜잭션으로 감싸면
+        // 충돌로 throw 할 때 그 앞에서 넣은 entity·relation·document 가 살아남는다
+        // (T17b 가 ghost entity 로 실증). import 전체가 한 단위여야 한다.
+        // 내부 transaction() 호출은 better-sqlite3 에서 savepoint 로 중첩된다.
+        const importAll = this.db.transaction(() => {
+            // If merge=false, clear existing data first
+            if (options.merge === false) {
+                this.db.exec(`DELETE FROM relationships`);
+                // entities 삭제가 FK CASCADE 로 lifecycle 4테이블을 지우지만, 순서를 계약으로
+                // 두어 FK 가 꺼진 환경에서도 잔존 행이 남지 않게 한다.
+                this.db.exec(`DELETE FROM observation_events`);
+                this.db.exec(`DELETE FROM observation_sources`);
+                this.db.exec(`DELETE FROM entity_observations`);
+                this.db.exec(`DELETE FROM observation_roots`);
+                this.db.exec(`DELETE FROM entities`);
+                this.db.exec(`DELETE FROM documents`);
+                // entities 를 지워도 파생 데이터는 따라오지 않는다: chunk_metadata 에는
+                // entities 로 가는 FK 가 없고 entity_embedding_metadata.entity_id 는 UNIQUE 일
+                // 뿐이다. 그래서 replace-import 뒤에 **사라진 entity 의 벡터와 KG chunk 가
+                // 검색에 남았다**(advisor beta 발견 2). document chunk 는 documents 의
+                // CASCADE 로 이미 정리되므로 여기서는 entity·relationship chunk 만 지운다.
+                const orphanChunks = this.db.prepare(`SELECT rowid FROM chunk_metadata WHERE chunk_type IN ('entity','relationship')`)
+                    .all();
+                for (const c of orphanChunks) {
+                    this.db.exec(`DELETE FROM chunks WHERE rowid = ${Number(c.rowid)}`);
+                    this.db.prepare(`DELETE FROM chunk_metadata WHERE rowid = ?`).run(c.rowid);
+                }
+                this.db.exec(`DELETE FROM entity_embeddings WHERE rowid IN (SELECT rowid FROM entity_embedding_metadata)`);
+                this.db.exec(`DELETE FROM entity_embedding_metadata`);
+                console.error('🗑️ Cleared existing data for full import');
+            }
+            // Import entities using INSERT OR IGNORE
+            if (data.entities && Array.isArray(data.entities)) {
+                const stmt = this.db.prepare(`
         INSERT OR IGNORE INTO entities (id, name, entityType, observations, metadata, created_at)
         VALUES (?, ?, ?, ?, ?, ?)
       `);
-            for (const entity of data.entities) {
-                const result = stmt.run(entity.id, entity.name, entity.entityType || 'CONCEPT', JSON.stringify(entity.observations || []), JSON.stringify(entity.metadata || {}), entity.created_at || new Date().toISOString());
-                if (result.changes > 0) {
-                    imported.entities++;
-                }
-                else {
-                    skipped.entities++;
+                for (const entity of data.entities) {
+                    const result = stmt.run(entity.id, entity.name, entity.entityType || 'CONCEPT', 
+                    // v13: observations 는 projection 이다. lifecycle 행을 넣은 뒤
+                    // rebuildProjection 이 채운다 — 여기서 배열을 심으면 정본과 갈라진다.
+                    '[]', JSON.stringify(entity.metadata || {}), entity.created_at || new Date().toISOString());
+                    if (result.changes > 0) {
+                        imported.entities++;
+                    }
+                    else {
+                        skipped.entities++;
+                    }
                 }
             }
-        }
-        // Import relations using INSERT OR IGNORE
-        if (data.relations && Array.isArray(data.relations)) {
-            const stmt = this.db.prepare(`
+            // Import relations using INSERT OR IGNORE
+            if (data.relations && Array.isArray(data.relations)) {
+                const stmt = this.db.prepare(`
         INSERT OR IGNORE INTO relationships (id, source_entity, target_entity, relationType, confidence, metadata, created_at)
         VALUES (?, ?, ?, ?, ?, ?, ?)
       `);
-            for (const relation of data.relations) {
-                const result = stmt.run(relation.id, relation.source_entity, relation.target_entity, relation.relationType, relation.confidence ?? 1.0, JSON.stringify(relation.metadata || {}), relation.created_at || new Date().toISOString());
-                if (result.changes > 0) {
-                    imported.relations++;
-                }
-                else {
-                    skipped.relations++;
+                for (const relation of data.relations) {
+                    const result = stmt.run(relation.id, relation.source_entity, relation.target_entity, relation.relationType, relation.confidence ?? 1.0, JSON.stringify(relation.metadata || {}), relation.created_at || new Date().toISOString());
+                    if (result.changes > 0) {
+                        imported.relations++;
+                    }
+                    else {
+                        skipped.relations++;
+                    }
                 }
             }
-        }
-        // Import documents using INSERT OR REPLACE
-        if (data.documents && Array.isArray(data.documents)) {
-            const stmt = this.db.prepare(`
+            // Import documents using INSERT OR REPLACE
+            if (data.documents && Array.isArray(data.documents)) {
+                const stmt = this.db.prepare(`
         INSERT OR REPLACE INTO documents (id, content, metadata, created_at)
         VALUES (?, ?, ?, ?)
       `);
-            for (const doc of data.documents) {
-                const result = stmt.run(doc.id, doc.content, JSON.stringify(doc.metadata || {}), doc.created_at || new Date().toISOString());
-                if (result.changes > 0) {
-                    imported.documents++;
-                }
-                else {
-                    skipped.documents++;
+                for (const doc of data.documents) {
+                    const result = stmt.run(doc.id, doc.content, JSON.stringify(doc.metadata || {}), doc.created_at || new Date().toISOString());
+                    if (result.changes > 0) {
+                        imported.documents++;
+                    }
+                    else {
+                        skipped.documents++;
+                    }
                 }
             }
-        }
+            // ---- spec §6.4: lifecycle import ----
+            // 순서가 계약이다: entities -> roots -> revisions(root별 revision_no ↑)
+            // -> sources/events. §4.1 트리거가 root 선행과 체인 연속성을 요구하므로
+            // importer 는 입력 순서와 무관하게 재정렬한다 (역순 export 를 그대로
+            // 스트리밍하면 'immediately preceding revision' 으로 죽는다).
+            const sameRow = (a, b, cols) => cols.every(c => (a[c] ?? null) === (b[c] ?? null));
+            const hasLifecycle = Array.isArray(data.observation_roots);
+            if (hasLifecycle) {
+                const tx = this.db.transaction(() => {
+                    // 새 root 가 이미 점유된 (entity_id, projection_order) 슬롯을 요구할 수 있다:
+                    // 두 DB 가 같은 entity 이름을 갖고 서로 다른 관찰을 배열 0번에 두면 그렇다.
+                    // 이건 §6.4 의 "같은 키 다른 값" 충돌이 아니라 **슬롯 충돌**이고, 규칙이 없어서
+                    // raw UNIQUE 오류로 터졌다(내 MCP 왕복 테스트가 잡았다). merge 의 뜻은
+                    // "더한다"이므로 들어오는 root 에 다음 빈 순번을 준다 — 남의 관찰을 덮지 않고,
+                    // 배열 끝에 붙는다. remap 은 그 root 의 revision 들에도 그대로 적용해야 한다
+                    // (trg_obs_matches_root 가 둘의 일치를 요구한다).
+                    // 입력 순서에 결과가 의존하면 같은 dump 를 두 번 넣었을 때 배열 순서가 달라진다.
+                    // (entity_id, projection_order, root_id) 로 정렬해 결정론을 만든다.
+                    const incomingRoots = [...(data.observation_roots ?? [])].sort((a, b) => String(a.entity_id).localeCompare(String(b.entity_id)) ||
+                        (a.projection_order - b.projection_order) ||
+                        String(a.root_id).localeCompare(String(b.root_id)));
+                    const remappedOrder = new Map();
+                    for (const r of incomingRoots) {
+                        const cur = this.db.prepare(`SELECT * FROM observation_roots WHERE root_id = ?`)
+                            .get(r.root_id);
+                        if (cur) {
+                            // projection_order 는 **target-local** 속성이다: merge 는 배열 위치를
+                            // 이 DB 기준으로 재배정하므로, 이미 remap 된 root 를 같은 dump 로 다시
+                            // 넣으면 dump 의 옛 순번과 다를 수밖에 없다. 그걸 충돌로 보면 동일
+                            // 재수입이 실패한다(advisor beta r3 발견 3, 실행 재현).
+                            if (!sameRow(cur, r, ['entity_id', 'created_at']))
+                                throw new Error(`import conflict: observation_roots ${r.root_id} differs from the existing row`);
+                            remappedOrder.set(r.root_id, cur.projection_order);
+                            continue;
+                        }
+                        let order = r.projection_order;
+                        const taken = this.db.prepare(`SELECT root_id FROM observation_roots WHERE entity_id = ? AND projection_order = ?`)
+                            .get(r.entity_id, order);
+                        if (taken) {
+                            order = nextProjectionOrder(this.db, r.entity_id);
+                            remappedOrder.set(r.root_id, order);
+                            remapReport.push({ root_id: r.root_id, entity_id: r.entity_id,
+                                from: r.projection_order, to: order });
+                            console.error(`  ├─ ↪️ import: ${r.entity_id} position ${r.projection_order} is held by ` +
+                                `${taken.root_id}; appending imported observation at ${order}`);
+                        }
+                        this.db.prepare(`INSERT INTO observation_roots
+            (root_id, entity_id, projection_order, created_at) VALUES (?, ?, ?, ?)`)
+                            .run(r.root_id, r.entity_id, order, r.created_at);
+                    }
+                    // projection_order 는 root 와 같은 이유로 비교 대상이 아니다(target-local).
+                    const revCols = ['root_id', 'entity_id', 'revision_no', 'content',
+                        'status', 'supersedes_id', 'recorded_at', 'superseded_at'];
+                    const revs = [...(data.entity_observations ?? [])]
+                        .sort((a, b) => a.root_id === b.root_id
+                        ? a.revision_no - b.revision_no
+                        : String(a.root_id).localeCompare(String(b.root_id)));
+                    for (const v of revs) {
+                        const cur = this.db.prepare(`SELECT * FROM entity_observations WHERE observation_id = ?`)
+                            .get(v.observation_id);
+                        if (cur) {
+                            if (!sameRow(cur, v, revCols))
+                                throw new Error(`import conflict: entity_observations ${v.observation_id} differs from the existing row`);
+                            continue;
+                        }
+                        const order = remappedOrder.has(v.root_id)
+                            ? remappedOrder.get(v.root_id) : v.projection_order;
+                        this.db.prepare(`INSERT INTO entity_observations
+            (observation_id, root_id, entity_id, revision_no, projection_order,
+             content, status, supersedes_id, recorded_at, superseded_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                            .run(v.observation_id, v.root_id, v.entity_id, v.revision_no, order, v.content, v.status, v.supersedes_id ?? null, v.recorded_at, v.superseded_at ?? null);
+                    }
+                    for (const so of (data.observation_sources ?? [])) {
+                        const cur = this.db.prepare(`SELECT * FROM observation_sources
+            WHERE observation_id=? AND source_kind=? AND source_ref=?`)
+                            .get(so.observation_id, so.source_kind, so.source_ref);
+                        if (cur) {
+                            if (!sameRow(cur, so, ['source_hash', 'recorded_at']))
+                                throw new Error(`import conflict: observation_sources ` +
+                                    `${so.observation_id}/${so.source_kind}/${so.source_ref} differs from the existing row`);
+                            continue;
+                        }
+                        this.db.prepare(`INSERT INTO observation_sources
+            (observation_id, source_kind, source_ref, source_hash, recorded_at) VALUES (?, ?, ?, ?, ?)`)
+                            .run(so.observation_id, so.source_kind, so.source_ref, so.source_hash ?? null, so.recorded_at);
+                    }
+                    const evCols = ['root_id', 'from_id', 'to_id', 'event', 'change_kind', 'reason', 'actor', 'batch_id', 'recorded_at'];
+                    for (const e of (data.observation_events ?? [])) {
+                        const cur = this.db.prepare(`SELECT * FROM observation_events WHERE event_id = ?`)
+                            .get(e.event_id);
+                        if (cur) {
+                            if (!sameRow(cur, e, evCols))
+                                throw new Error(`import conflict: observation_events ${e.event_id} differs from the existing row`);
+                            continue;
+                        }
+                        this.db.prepare(`INSERT INTO observation_events
+            (event_id, root_id, from_id, to_id, event, change_kind, reason, actor, batch_id, recorded_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                            .run(e.event_id, e.root_id, e.from_id ?? null, e.to_id ?? null, e.event, e.change_kind ?? null, e.reason ?? null, e.actor ?? null, e.batch_id ?? null, e.recorded_at);
+                    }
+                });
+                tx();
+            }
+            else {
+                // 구(舊) 형식 export: lifecycle 필드가 없으므로 entities.observations 를
+                // 신규 root 로 승격한다. legacy import 필수 필드값 = spec §6.4.
+                const ts = new Date().toISOString();
+                const tx = this.db.transaction(() => {
+                    for (const ent of (data.entities ?? [])) {
+                        const entityId = ent.id ??
+                            `entity_${String(ent.name).toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`;
+                        for (const content of (ent.observations ?? [])) {
+                            addRevision(this.db, {
+                                entityId, content, status: 'active',
+                                sources: [{ source_kind: 'import', source_ref: 'legacy-export', source_hash: null }],
+                                actor: 'import', ts, event: 'import'
+                            });
+                        }
+                    }
+                });
+                tx();
+            }
+            // projection 재합성 + 파생 상태 무효화.
+            // 무효화가 없으면 이미 있던 entity 를 덮어쓴 뒤에도 옛 벡터·옛 KG chunk 가
+            // 검색에 남는다. import 는 관찰을 바꾸는 writer 이므로 다른 writer 와 같은
+            // 계약을 져야 한다(advisor beta 발견 2).
+            //
+            // 대상은 `data.entities` 가 아니라 **영향받은 entity 전부**다. lifecycle import 는
+            // observation_roots 만 있어도 활성화되므로, entities 없이 lifecycle 배열만 보내면
+            // revision 은 들어가는데 projection 이 갱신되지 않아 새 사실이 reader 에 안 보이고
+            // 옛 벡터가 남는다(advisor beta r3 발견 2, 실행 재현).
+            const affected = new Set();
+            for (const ent of (data.entities ?? [])) {
+                affected.add(ent.id ??
+                    `entity_${String(ent.name).toLowerCase().replace(/[^\p{L}\p{N}]/gu, '_')}`);
+            }
+            for (const r of (data.observation_roots ?? []))
+                if (r.entity_id)
+                    affected.add(r.entity_id);
+            for (const v of (data.entity_observations ?? []))
+                if (v.entity_id)
+                    affected.add(v.entity_id);
+            for (const entityId of affected) {
+                rebuildProjection(this.db, entityId);
+                this.invalidateDerivedForEntity(entityId);
+            }
+        });
+        importAll();
         console.error(`✅ Import completed: ${imported.entities} entities, ${imported.relations} relations, ${imported.documents} documents imported`);
-        return { imported, skipped };
+        // Indirect missing-row producer (spec §5): imported rows may lack vectors.
+        this.coordinator?.invalidateCoverage();
+        this.coordinator?.kick();
+        return { imported, skipped, observation_order_remap: remapReport };
     }
     async hybridSearch(query, limit = 5, useGraph = true) {
         if (!this.db)
@@ -1819,6 +2713,9 @@ export class RAGKnowledgeGraphManager {
         if (!this.encoding)
             throw new Error('Tokenizer not initialized');
         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.
+        const ftsUnsearchable = compileFtsLiteralQuery(query) === null;
         const queryVariants = this.buildCrossLingualVariants(query);
         if (queryVariants.length > 1) {
             console.error(`🌐 Cross-lingual variants: ${queryVariants.slice(1).join(' | ')}`);
@@ -1853,37 +2750,47 @@ export class RAGKnowledgeGraphManager {
       `).all(Buffer.from(embedding.buffer), k);
         };
         // Search original query plus cross-lingual expansions and keep best match per chunk.
+        // v3.6 eligibility gate (spec §3): vector usage requires model_ready AND
+        // reconciliation settled — otherwise FTS5-only, no waiting.
         const resultMap = new Map();
-        try {
-            primaryQueryEmbedding = await this.generateEmbedding(queryVariants[0], 1024, true);
-            for (const variant of queryVariants) {
-                const embedding = await this.generateEmbedding(variant, 1024, true);
-                const variantResults = searchChunks(embedding, limit * 3);
-                for (const r of variantResults) {
-                    const existing = resultMap.get(r.chunk_id);
-                    if (!existing || r.distance < existing.distance) {
-                        resultMap.set(r.chunk_id, r);
+        let degradationReason;
+        if (!(this.coordinator?.eligible ?? false)) {
+            vectorDegraded = true;
+            degradationReason = this.degradationReason();
+            console.error(`ℹ️ vector search not eligible (${degradationReason ?? 'unknown'}) — FTS5-only`);
+        }
+        else {
+            try {
+                primaryQueryEmbedding = await this.generateEmbedding(queryVariants[0], 1024, true);
+                for (const variant of queryVariants) {
+                    const embedding = await this.generateEmbedding(variant, 1024, true);
+                    const variantResults = searchChunks(embedding, limit * 3);
+                    for (const r of variantResults) {
+                        const existing = resultMap.get(r.chunk_id);
+                        if (!existing || r.distance < existing.distance) {
+                            resultMap.set(r.chunk_id, r);
+                        }
                     }
                 }
             }
-        }
-        catch (embErr) {
-            vectorDegraded = true;
-            console.error(`⚠️ Vector search unavailable (embedding model down) — degrading to FTS5-only:`, embErr instanceof Error ? embErr.message : embErr);
+            catch (embErr) {
+                vectorDegraded = true;
+                // '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';
+                console.error(`⚠️ Vector search unavailable — degrading to FTS5-only:`, embErr instanceof Error ? embErr.message : embErr);
+            }
         }
         const vectorResults = Array.from(resultMap.values()).sort((a, b) => a.distance - b.distance);
         // FTS5 full-text search as additional signal (Reciprocal Rank Fusion)
         const ftsBoostMap = new Map();
         try {
             const ftsSearchQuery = (q) => {
-                // Escape FTS5 special characters and build a query with OR between terms
-                const sanitized = q.replace(/["\*\(\)\-]/g, ' ').trim();
-                if (!sanitized)
-                    return [];
-                const terms = sanitized.split(/\s+/).filter(t => t.length > 0);
-                if (terms.length === 0)
+                // Shared compiler (spec §5) — same sanitize rules as pre-3.6, extracted
+                // so entity FTS fallback uses identical MATCH-safety guarantees.
+                const ftsExpr = compileFtsLiteralQuery(q);
+                if (ftsExpr === null)
                     return [];
-                const ftsExpr = terms.map(t => `"${t}"`).join(' OR ');
                 return this.db.prepare(`
           SELECT cm.rowid, cm.chunk_id, bm25(chunks_fts) as fts_score
           FROM chunks_fts
@@ -1953,7 +2860,19 @@ export class RAGKnowledgeGraphManager {
         }
         if (vectorResults.length === 0) {
             console.error(`ℹ️ No vector or FTS5 matches found for "${query}"`);
-            return [];
+            // Empty results still carry state (spec §5c: envelope exists so callers
+            // can distinguish "nothing matched" from "vector search was degraded").
+            const covE = this.coordinator?.coverage();
+            const chunkPctE = covE && covE.chunk.total > 0 ? Math.round((covE.chunk.embedded / covE.chunk.total) * 100) : 100;
+            const graphPctE = covE && covE.entity.total > 0 ? Math.round((covE.entity.embedded / covE.entity.total) * 100) : 100;
+            return {
+                results: [],
+                search_mode: vectorDegraded ? 'fts-only' : (chunkPctE < 100 ? 'hybrid-partial' : 'hybrid'),
+                model_state: this.gate.status.state,
+                coverage: { chunk_pct: chunkPctE, graph_coverage_pct: graphPctE },
+                ...(degradationReason ? { degradation_reason: degradationReason } : {}),
+                ...(ftsUnsearchable ? { warning: 'query has no searchable terms for FTS' } : {}),
+            };
         }
         // Get entity information for graph enhancement via vector similarity
         let connectedEntities = new Set();
@@ -2157,8 +3076,7 @@ export class RAGKnowledgeGraphManager {
                 fts_boost: ftsBoost > 0 ? ftsBoost : undefined,
                 full_context_available: true,
                 chunk_type: result.chunk_type,
-                source_id: sourceId,
-                search_mode: vectorDegraded ? 'fts-only' : 'hybrid'
+                source_id: sourceId
             });
         }
         // Sort by relevance and return top results
@@ -2170,7 +3088,34 @@ export class RAGKnowledgeGraphManager {
         const entityResults = finalResults.filter(r => r.chunk_type === 'entity').length;
         const relResults = finalResults.filter(r => r.chunk_type === 'relationship').length;
         console.error(`✅ Enhanced hybrid search completed: ${finalResults.length} results (${docResults} docs, ${entityResults} entities, ${relResults} relationships)`);
-        return finalResults;
+        // v3.6 envelope (spec §5c, breaking): search_mode moved from per-item to
+        // top-level so state is visible even on empty results; coverage tells the
+        // caller how much of the corpus is actually vector-searchable.
+        const cov = this.coordinator?.coverage();
+        const chunkPct = cov && cov.chunk.total > 0 ? Math.round((cov.chunk.embedded / cov.chunk.total) * 100) : 100;
+        const graphPct = cov && cov.entity.total > 0 ? Math.round((cov.entity.embedded / cov.entity.total) * 100) : 100;
+        const search_mode = vectorDegraded ? 'fts-only' : (chunkPct < 100 ? 'hybrid-partial' : 'hybrid');
+        return {
+            results: finalResults,
+            search_mode,
+            model_state: this.gate.status.state,
+            coverage: { chunk_pct: chunkPct, graph_coverage_pct: graphPct },
+            ...(degradationReason ? { degradation_reason: degradationReason } : {}),
+            ...(ftsUnsearchable ? { warning: 'query has no searchable terms for FTS' } : {}),
+        };
+    }
+    // v3.6 (spec §5c / 6R note 2): why is vector search degraded right now?
+    degradationReason() {
+        if (this.gate.isDisabled)
+            return 'disabled';
+        if (!this.gate.isReady)
+            return 'model_not_ready';
+        const rs = this.coordinator?.reconState;
+        if (rs === 'failed')
+            return 'reconciliation_failed';
+        if (rs && rs !== 'complete' && rs !== 'n/a')
+            return 'reconciling';
+        return undefined;
     }
     // NEW: Get detailed context for a specific chunk
     async getDetailedContext(chunkId, includeSurrounding = true) {
@@ -2261,6 +3206,10 @@ export class RAGKnowledgeGraphManager {
         const chunkCount = this.db.prepare(`
       SELECT COUNT(*) as count FROM chunk_metadata
     `).get();
+        // v3.6 (spec §8-2, additive): server self-report — the framework's /start
+        // reads version, model/reconciliation state, and provenance coverage here.
+        const gs = this.gate.status;
+        const cov = this.coordinator?.coverage();
         return {
             entities: {
                 total: entityStats.reduce((sum, stat) => sum + stat.count, 0),
@@ -2271,7 +3220,23 @@ export class RAGKnowledgeGraphManager {
                 by_type: Object.fromEntries(relationshipStats.map(s => [s.relationType, s.count]))
             },
             documents: documentCount.count,
-            chunks: chunkCount.count
+            chunks: chunkCount.count,
+            server: {
+                version: PKG_VERSION,
+                node: process.versions.node,
+                embeddings_mode: this.embeddingsMode,
+                model: `${EMBEDDING_MODEL}@${MODEL_REVISION}`,
+                model_state: gs.state,
+                ready_since: gs.readySince ?? null,
+                last_error: gs.lastError ? sanitizeErrorMessage(gs.lastError) : null,
+                retry_at: gs.retryAt ?? null,
+                reconciliation_state: this.coordinator?.reconState ?? 'n/a',
+                reconciliation_last_error: this.coordinator?.reconLastError ?? null,
+                coverage: cov ? {
+                    chunk: { total: cov.chunk.total, embedded: cov.chunk.embedded, verified: cov.chunk.verified, legacy_assumed: cov.chunk.legacy_assumed, missing: cov.chunk.total - cov.chunk.embedded },
+                    entity: { total: cov.entity.total, embedded: cov.entity.embedded, verified: cov.entity.verified, legacy_assumed: cov.entity.legacy_assumed, missing: cov.entity.total - cov.entity.embedded },
+                } : null,
+            }
         };
     }
     // === GRAPH ANALYTICS TOOLS (graphology) ===
@@ -2595,13 +3560,39 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             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":
-                await ragKgManager.deleteObservations(validatedArgs.deletions);
-                return { content: [{ type: "text", text: "Observations deleted successfully" }] };
+                // 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" }] };
@@ -2672,35 +3663,95 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
     }
     catch (error) {
+        // v3.6 (spec §5c): machine-distinguishable failures. Embedding-gate errors
+        // become structured retryable/terminal payloads; every error response now
+        // sets isError so clients stop parsing "Error: ..." strings.
+        if (error instanceof GateNotReadyError) {
+            return { isError: true, content: [{ type: "text", text: JSON.stringify({
+                            code: error.code, state: error.state,
+                            ...(error.retryAfterMs !== undefined ? { retry_after_ms: error.retryAfterMs } : {}),
+                            message: error.message
+                        }) }] };
+        }
+        if (error instanceof GateDisabledError) {
+            return { isError: true, content: [{ type: "text", text: JSON.stringify({
+                            code: error.code, state: error.state, message: error.message
+                        }) }] };
+        }
         if (error instanceof Error) {
             console.error(`❌ Tool execution error for ${name}:`, error.message);
-            return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+            return { isError: true, content: [{ type: "text", text: `Error: ${error.message}` }] };
         }
         throw error;
     }
 });
 async function main() {
     try {
+        assertNodeVersion();
         await ragKgManager.initialize();
+        printBanner({
+            model: EMBEDDING_MODEL, revision: MODEL_REVISION, dtype: MODEL_DTYPE,
+            cachePath: resolveModelCacheDir(process.env, process.platform, os.homedir()),
+            dbPath: DB_FILE_PATH,
+        });
+        if (ragKgManager.embeddingsMode === 'eager') {
+            // eager = wait for BOTH the first model load attempt and reconciliation to
+            // settle (success or failure) before connecting — v3.5-equivalent boot
+            // extended to legacy DBs (spec §9). Failures fall back to background retry.
+            await Promise.allSettled([ragKgManager.gate.start(), ragKgManager.startReconciliation()]);
+        }
         const transport = new StdioServerTransport();
         await server.connect(transport);
         console.error("🚀 Enhanced RAG Knowledge Graph MCP Server running on stdio");
-        // Cleanup on exit — avoid process.exit() to prevent ONNX runtime mutex crash
+        if (ragKgManager.embeddingsMode === 'lazy') {
+            // Background: model load + provenance reconciliation run in parallel.
+            // Failures surface via gate/coordinator state, never as rejections.
+            void ragKgManager.gate.start().catch(() => { });
+            void ragKgManager.startReconciliation().catch(() => { });
+        }
+        else if (ragKgManager.embeddingsMode === 'off') {
+            // off mode still CLASSIFIES reconciliation state (deferred vs n/a) so
+            // stats honor the mode matrix — no sanitation, no inference (beta B7).
+            void ragKgManager.startReconciliation().catch(() => { });
+        }
+        // Graceful shutdown (spec §3 order, beta-2R-amended) — transport close
+        // FIRST so stdin stops holding the event loop, then settle coordinator and
+        // gate, then DB close. process.exit is forbidden EXCEPT the one spec'd
+        // case: a model load/download still pending after the settle deadline
+        // (un-abortable fetch would hold the loop forever) — see shutdownAll.
+        let shuttingDown = false;
         const shutdown = () => {
-            console.error('\n🧹 Cleaning up...');
-            try {
-                ragKgManager.cleanup();
-            }
-            catch { }
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            void (async () => {
+                try {
+                    await server.close();
+                }
+                catch { /* transport already gone */ }
+                try {
+                    process.stdin.pause();
+                    process.stdin.unref?.();
+                }
+                catch { /* best-effort */ }
+                await ragKgManager.shutdownAll();
+            })();
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
-        process.on('exit', shutdown);
+        process.on('exit', () => { try {
+            ragKgManager.cleanup();
+        }
+        catch { /* idempotent */ } });
+        console.error('🛡️ shutdown handlers registered'); // deterministic handler-ready marker (5R test residual)
     }
     catch (error) {
         console.error("Failed to initialize server:", error);
-        ragKgManager.cleanup();
-        process.exit(1);
+        try {
+            ragKgManager.cleanup();
+        }
+        catch { /* already down */ }
+        process.exitCode = 1;
     }
 }
 // Boot the server unless explicitly suppressed. Tests import this module with
@@ -2711,7 +3762,10 @@ async function main() {
 if (process.env.RAG_MEMORY_NO_AUTOSTART !== '1') {
     main().catch((error) => {
         console.error("Fatal error in main():", error);
-        ragKgManager.cleanup();
-        process.exit(1);
+        try {
+            ragKgManager.cleanup();
+        }
+        catch { /* already down */ }
+        process.exitCode = 1;
     });
 }