rag-memory-epf-mcp 3.5.1 → 3.6.0

package/dist/index.js

@@ -24,10 +24,52 @@ import { MigrationManager } from './src/migrations/migration-manager.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 +82,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 +116,23 @@ 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).
     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 +140,286 @@ 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)');
-        }
-        // Run database migrations
         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.
+    mutateEntityAndInvalidate(entityId, mutate) {
+        const tx = this.db.transaction(() => {
+            mutate();
+            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);
+            }
+        });
+        tx();
+        this.coordinator?.invalidateCoverage();
+    }
+    // §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() {
@@ -140,11 +451,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();
@@ -173,10 +479,11 @@ export class RAGKnowledgeGraphManager {
             // 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 });
+                // New entity created. CRUD success is independent of model readiness
+                // (spec §5): not-ready -> row stays vectorless (queued for backfill).
                 console.error(`🔮 Generating embedding for new entity: ${entity.name}`);
-                await this.embedEntity(entityId);
+                const embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
+                result.push({ ...entity, observations: timestamped, embedding_status });
             }
             else {
                 // Entity already exists — upsert: merge observations and update entityType
@@ -192,11 +499,13 @@ export class RAGKnowledgeGraphManager {
                     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);
+                        this.mutateEntityAndInvalidate(entityId, () => {
+                            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 embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
+                        result.push({ ...entity, observations: mergedObs, embedding_status });
                     }
                 }
             }
@@ -208,24 +517,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) {
@@ -248,12 +565,16 @@ export class RAGKnowledgeGraphManager {
             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
+                this.mutateEntityAndInvalidate(entityId, () => {
+                    this.db.prepare(`
+            UPDATE entities SET observations = ? WHERE id = ?
+          `).run(JSON.stringify(updatedObservations), entityId);
+                });
+                // Regenerate embedding for the updated entity (queued when not ready)
                 console.error(`🔮 Regenerating embedding for updated entity: ${obs.entityName}`);
-                await this.embedEntity(entityId);
+                const embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
+                results.push({ entityName: obs.entityName, addedObservations: newObservations, embedding_status });
+                continue;
             }
             results.push({ entityName: obs.entityName, addedObservations: newObservations });
         }
@@ -322,22 +643,40 @@ 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.
     async deleteObservations(deletions) {
         if (!this.db)
             throw new Error('Database not initialized');
+        const results = [];
+        let total = 0;
         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);
+            if (!entity) {
+                results.push({ entityName: deletion.entityName, deleted: 0, embedding_status: 'n/a' });
+                continue;
+            }
+            const currentObservations = JSON.parse(entity.observations);
+            const filteredObservations = currentObservations.filter((obs) => !deletion.observations.includes(obs));
+            const deleted = currentObservations.length - filteredObservations.length;
+            if (deleted === 0) {
+                results.push({ entityName: deletion.entityName, deleted: 0, embedding_status: 'n/a' });
+                continue;
             }
+            this.mutateEntityAndInvalidate(entityId, () => {
+                this.db.prepare(`UPDATE entities SET observations = ? WHERE id = ?`)
+                    .run(JSON.stringify(filteredObservations), entityId);
+            });
+            const embedding_status = await this.tryEmbedEntity(entityId, 'bulk');
+            total += deleted;
+            results.push({ entityName: deletion.entityName, deleted, embedding_status });
         }
+        return { results, total_deleted: total };
     }
     async deleteRelations(relations) {
         if (!this.db)
@@ -524,10 +863,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 +904,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 +939,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)
@@ -638,12 +1045,49 @@ export class RAGKnowledgeGraphManager {
         return { entities, relations };
     }
     // === NEW RAG FUNCTIONALITY ===
-    // Generate embedding text for an entity (combines name, type, and observations)
+    // Generate embedding text for an entity (identity + newest observations within a char budget).
     generateEntityEmbeddingText(entity) {
-        const observationsText = entity.observations
-            .filter(o => !o.startsWith('Source:') && !o.startsWith('Created:') && !o.startsWith('Type:') && !o.startsWith('Tags:') && !o.startsWith('Content length:'))
-            .join('. ');
-        return `${entity.entityType}: ${entity.name}. ${observationsText}`.trim();
+        return this.buildEntityEmbeddingText(entity).text;
+    }
+    // Build entity embedding text plus stats for instrumentation.
+    // The char budget keeps the entity vector representative of CURRENT state and stays under the
+    // bge-m3 8192-token ceiling; older history lives in RAG document chunks / dated entities.
+    // Returns selected/total observation counts and filtered (pre-cap) vs capped observation char
+    // sizes so callers can log truncation accurately (identity prefix is excluded from these sizes).
+    buildEntityEmbeddingText(entity) {
+        const maxObservationChars = Math.max(1000, Number.parseInt(process.env.ENTITY_EMBED_OBS_CHAR_BUDGET || '12000', 10) || 12000);
+        const observations = entity.observations.filter(o => !o.startsWith('Source:') && !o.startsWith('Created:') && !o.startsWith('Type:') &&
+            !o.startsWith('Tags:') && !o.startsWith('Content length:'));
+        const filteredObsChars = observations.join('. ').length;
+        const selected = [];
+        let remaining = maxObservationChars;
+        for (let i = observations.length - 1; i >= 0 && remaining > 0; i--) {
+            const obs = observations[i];
+            const separatorCost = selected.length > 0 ? 2 : 0; // '. ' joiner
+            const available = remaining - separatorCost;
+            if (available <= 0)
+                break;
+            if (obs.length <= available) {
+                selected.push(obs);
+                remaining -= obs.length + separatorCost;
+            }
+            else if (selected.length === 0) {
+                selected.push(obs.slice(0, available)); // single giant obs: keep a truncated head, never empty
+                break;
+            }
+            else {
+                break;
+            }
+        }
+        const observationsText = selected.reverse().join('. ');
+        const text = `${entity.entityType}: ${entity.name}. ${observationsText}`.trim();
+        return {
+            text,
+            filteredObsChars,
+            cappedObsChars: observationsText.length,
+            selectedObsCount: selected.length,
+            totalObsCount: observations.length,
+        };
     }
     // NEW: Generic semantic summary generation methods
     splitIntoSentences(text) {
@@ -763,7 +1207,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
@@ -775,32 +1219,53 @@ export class RAGKnowledgeGraphManager {
             return false;
         }
         const parsedObservations = JSON.parse(entity.observations);
-        const embeddingText = this.generateEntityEmbeddingText({
+        const built = this.buildEntityEmbeddingText({
             name: entity.name,
             entityType: entity.entityType,
             observations: parsedObservations
         });
-        // Generate embedding
-        const embedding = await this.generateEmbedding(embeddingText);
+        const embeddingText = built.text;
+        // Instrumentation (stderr only): observations kept vs total, filtered pre-cap vs capped obs
+        // 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, 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);
@@ -823,6 +1288,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
@@ -902,15 +1368,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) {
@@ -919,6 +1390,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) }) };
     }
@@ -1142,37 +1614,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 = {}) {
@@ -1200,31 +1658,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 });
         }
-        // 4. Atomic swap: delete old -> insert doc -> insert chunks + embeddings,
-        //    all in a single synchronous better-sqlite3 transaction (all-or-nothing).
+        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
+        //    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).
@@ -1238,7 +1721,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(`
@@ -1246,11 +1730,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);
@@ -1266,6 +1757,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) {
@@ -1323,6 +1815,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) {
@@ -1339,18 +1835,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) {
@@ -1360,6 +1858,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) }) };
@@ -1768,6 +2267,9 @@ export class RAGKnowledgeGraphManager {
             }
         }
         console.error(`✅ Import completed: ${imported.entities} entities, ${imported.relations} relations, ${imported.documents} documents imported`);
+        // Indirect missing-row producer (spec §5): imported rows may lack vectors.
+        this.coordinator?.invalidateCoverage();
+        this.coordinator?.kick();
         return { imported, skipped };
     }
     async hybridSearch(query, limit = 5, useGraph = true) {
@@ -1776,6 +2278,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(' | ')}`);
@@ -1810,37 +2315,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
@@ -1910,7 +2425,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();
@@ -2114,8 +2641,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
@@ -2127,7 +2653,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) {
@@ -2218,6 +2771,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),
@@ -2228,7 +2785,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) ===
@@ -2557,8 +3130,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 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" }] };
@@ -2629,35 +3203,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
@@ -2668,7 +3302,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;
     });
 }