@dzhechkov/harness-core 0.3.86 → 0.3.90

package/src/agentdb-index.ts

@@ -16,6 +16,13 @@ import { existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
+import {
+  currentEmbedManifest,
+  guardEmbedSpace,
+  readEmbedManifest,
+  resolveEmbedModel,
+  writeEmbedManifest,
+} from './embedding-config.js';
 
 /** One record to index. `text` is stored as `approach` AND embedded (`${taskType}: ${text}`). */
 export interface AgentdbRow {
@@ -36,7 +43,10 @@ export interface AgentdbIndexResult {
 interface NativeDb {
   pragma: (s: string) => void;
   exec: (s: string) => void;
-  prepare: (q: string) => { run: (...a: unknown[]) => { lastInsertRowid: number | bigint } };
+  prepare: (q: string) => {
+    run: (...a: unknown[]) => { lastInsertRowid: number | bigint };
+    get: (...a: unknown[]) => unknown;
+  };
   transaction: <T>(fn: (...a: unknown[]) => T) => (...a: unknown[]) => T;
   close: () => void;
 }
@@ -93,14 +103,24 @@ export async function indexPatternsToAgentdb(
     const { EmbeddingService } = (await import(pathToFileURL(join(agentdbDir, 'controllers', 'EmbeddingService.js')).href)) as {
       EmbeddingService: new (o: object) => { initialize: () => Promise<void>; embed: (t: string) => Promise<Float32Array> };
     };
-    const emb = new EmbeddingService({ model: 'Xenova/all-MiniLM-L6-v2', dimension: 384, provider: 'transformers' });
+    const model = resolveEmbedModel(projectRoot);
+    if ('error' in model) return { indexed: 0, error: model.error };
+    const emb = new EmbeddingService({ model: model.model, dimension: model.dim, provider: 'transformers' });
     await emb.initialize();
 
-    const db = new Database(resolveAgentdbPath(projectRoot, opts.dbPath));
+    const dbFile = resolveAgentdbPath(projectRoot, opts.dbPath);
+    const db = new Database(dbFile);
     try {
       db.pragma('journal_mode = WAL');
       db.pragma('busy_timeout = 5000'); // wait out a brief MCP-server write lock instead of failing
       db.exec(REASONING_BANK_SCHEMA);
+      const guard = guardEmbedSpace({
+        storePath: dbFile,
+        configured: model,
+        hasRows: embeddingRowCount(db) > 0,
+        reindexHint: 'dz vector reindex',
+      });
+      if (!guard.ok) return { indexed: 0, error: guard.error };
       const insPattern = db.prepare('INSERT INTO reasoning_patterns (task_type, approach, success_rate, uses, avg_reward, tags, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)');
       const insEmb = db.prepare('INSERT OR REPLACE INTO pattern_embeddings (pattern_id, embedding) VALUES (?, ?)');
       // Embeddings are async (can't run inside better-sqlite3's sync transaction) — compute them
@@ -119,7 +139,9 @@ export async function indexPatternsToAgentdb(
         }
         return prepared.length;
       });
-      return { indexed: commit() as number };
+      const indexed = commit() as number;
+      writeEmbedManifest(dbFile, currentEmbedManifest(model, guard.manifest.version, 'agentdb'));
+      return { indexed };
     } finally {
       db.close();
     }
@@ -167,8 +189,8 @@ const DEPS_MISSING = 'agentdb/better-sqlite3 not installed in project (run: dz s
 
 /**
  * Resolve agentdb's `EmbeddingService` from the PROJECT (same dynamic-resolution discipline as
- * {@link indexPatternsToAgentdb}; model pinned to `Xenova/all-MiniLM-L6-v2` dim 384 — every dz
- * call site MUST use this one embedder so query and row vectors stay in the same space).
+ * {@link indexPatternsToAgentdb}); every dz call site uses the same resolved model so query and row
+ * vectors stay in the same space.
  */
 export async function resolveAgentdbEmbedder(
   projectRoot: string,
@@ -184,7 +206,9 @@ export async function resolveAgentdbEmbedder(
     const { EmbeddingService } = (await import(pathToFileURL(join(agentdbDir, 'controllers', 'EmbeddingService.js')).href)) as {
       EmbeddingService: new (o: object) => { initialize: () => Promise<void>; embed: (t: string) => Promise<Float32Array> };
     };
-    const emb = new EmbeddingService({ model: 'Xenova/all-MiniLM-L6-v2', dimension: 384, provider: 'transformers' });
+    const model = resolveEmbedModel(projectRoot);
+    if ('error' in model) return { error: model.error };
+    const emb = new EmbeddingService({ model: model.model, dimension: model.dim, provider: 'transformers' });
     await emb.initialize();
     return { embed: (t: string) => emb.embed(t) };
   } catch (err) {
@@ -218,6 +242,11 @@ function hasDzTables(db: ReadonlyDb): boolean {
   return t('reasoning_patterns') && t('pattern_embeddings');
 }
 
+function embeddingRowCount(db: { prepare: (q: string) => { get: (...a: unknown[]) => unknown } }): number {
+  const row = db.prepare('SELECT COUNT(*) AS n FROM pattern_embeddings').get() as { n?: unknown } | undefined;
+  return typeof row?.n === 'number' ? row.n : 0;
+}
+
 /**
  * Cosine similarity in [-1, 1] over two embeddings. Exported (was file-private) so
  * `harmonizeVectorStore` scores near-duplicate pairs with the IDENTICAL math the semantic search
@@ -241,7 +270,7 @@ function dzIdOf(metadataJson: unknown): string | undefined {
   if (typeof metadataJson !== 'string' || metadataJson === '') return undefined;
   try {
     const meta = JSON.parse(metadataJson) as Record<string, unknown>;
-    const id = meta['dzId'] ?? meta['dreamId'];
+    const id = meta['dzId'] ?? meta['dreamId'] ?? meta['kuId'] ?? meta['ku_id'];
     return typeof id === 'string' ? id : undefined;
   } catch {
     return undefined;
@@ -258,31 +287,41 @@ function dzIdOf(metadataJson: unknown): string | undefined {
 export async function searchAgentdbPatterns(
   projectRoot: string,
   query: string,
-  opts: { limit?: number; dbPath?: string } = {},
+  opts: { limit?: number; dbPath?: string; taskTypes?: readonly string[]; reindexHint?: string } = {},
 ): Promise<AgentdbSearchResult> {
   const limit = Math.max(1, opts.limit ?? 10);
-  const emb = await resolveAgentdbEmbedder(projectRoot);
-  if ('error' in emb) return { hits: [], error: emb.error };
-  let qvec: Float32Array;
-  try {
-    qvec = await emb.embed(query);
-  } catch (err) {
-    return { hits: [], error: `query embed failed: ${err instanceof Error ? err.message : String(err)}` };
-  }
   const opened = openReadonly(projectRoot, opts.dbPath);
   if ('absent' in opened) return { hits: [] }; // nothing mirrored yet — zero semantic hits, honestly
   if ('error' in opened) return { hits: [], error: opened.error };
   const { db } = opened;
   try {
     if (!hasDzTables(db)) return { hits: [] };
-    const placeholders = DZ_TASK_TYPES.map(() => '?').join(', ');
+    const taskTypes = opts.taskTypes ?? DZ_TASK_TYPES;
+    const placeholders = taskTypes.map(() => '?').join(', ');
     const rows = db
       .prepare(
         `SELECT p.id, p.approach, p.success_rate, p.metadata, e.embedding
          FROM reasoning_patterns p JOIN pattern_embeddings e ON e.pattern_id = p.id
          WHERE p.task_type IN (${placeholders})`,
       )
-      .all(...DZ_TASK_TYPES) as Array<{ id: number; approach: string; success_rate: number; metadata: string | null; embedding: Buffer }>;
+      .all(...taskTypes) as Array<{ id: number; approach: string; success_rate: number; metadata: string | null; embedding: Buffer }>;
+    const model = resolveEmbedModel(projectRoot);
+    if ('error' in model) return { hits: [], error: model.error };
+    const guard = guardEmbedSpace({
+      storePath: resolveAgentdbPath(projectRoot, opts.dbPath),
+      configured: model,
+      hasRows: rows.length > 0,
+      reindexHint: opts.reindexHint ?? 'dz vector reindex',
+    });
+    if (!guard.ok) return { hits: [], error: guard.error };
+    const emb = await resolveAgentdbEmbedder(projectRoot);
+    if ('error' in emb) return { hits: [], error: emb.error };
+    let qvec: Float32Array;
+    try {
+      qvec = await emb.embed(query);
+    } catch (err) {
+      return { hits: [], error: `query embed failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
     const scored: AgentdbSearchHit[] = rows.map((r) => {
       const vec = new Float32Array(r.embedding.buffer, r.embedding.byteOffset, Math.floor(r.embedding.byteLength / 4));
       return {
@@ -309,7 +348,7 @@ export async function searchAgentdbPatterns(
  */
 export async function listAgentdbDzIds(
   projectRoot: string,
-  opts: { dbPath?: string } = {},
+  opts: { dbPath?: string; taskTypes?: readonly string[] } = {},
 ): Promise<{ ids: string[]; error?: string | undefined }> {
   const opened = openReadonly(projectRoot, opts.dbPath);
   if ('absent' in opened) return { ids: [] }; // empty mirror — everything is backfillable
@@ -317,10 +356,11 @@ export async function listAgentdbDzIds(
   const { db } = opened;
   try {
     if (!hasDzTables(db)) return { ids: [] };
-    const placeholders = DZ_TASK_TYPES.map(() => '?').join(', ');
+    const taskTypes = opts.taskTypes ?? DZ_TASK_TYPES;
+    const placeholders = taskTypes.map(() => '?').join(', ');
     const rows = db
       .prepare(`SELECT metadata FROM reasoning_patterns WHERE task_type IN (${placeholders})`)
-      .all(...DZ_TASK_TYPES) as Array<{ metadata: string | null }>;
+      .all(...taskTypes) as Array<{ metadata: string | null }>;
     const ids = new Set<string>();
     for (const r of rows) {
       const id = dzIdOf(r.metadata);
@@ -389,6 +429,8 @@ export async function importVectorsToAgentdb(
   }
   try {
     const { default: Database } = (await import(sqliteUrl)) as { default: new (p: string) => UpsertDb };
+    const model = resolveEmbedModel(projectRoot);
+    if ('error' in model) return { imported: 0, error: model.error };
     const dbFile = resolveAgentdbPath(projectRoot, opts.dbPath);
     mkdirSync(dirname(dbFile), { recursive: true }); // better-sqlite3 won't create the parent dir
     const db = new Database(dbFile);
@@ -396,6 +438,13 @@ export async function importVectorsToAgentdb(
       db.pragma('journal_mode = WAL');
       db.pragma('busy_timeout = 5000'); // wait out a brief MCP-server write lock instead of failing
       db.exec(REASONING_BANK_SCHEMA);
+      const guard = guardEmbedSpace({
+        storePath: dbFile,
+        configured: model,
+        hasRows: embeddingRowCount(db) > 0,
+        reindexHint: 'dz vector reindex',
+      });
+      if (!guard.ok) return { imported: 0, error: guard.error };
       const findByDzId = db.prepare("SELECT id FROM reasoning_patterns WHERE json_extract(metadata, '$.dzId') = ?");
       const insPattern = db.prepare('INSERT INTO reasoning_patterns (task_type, approach, success_rate, uses, avg_reward, tags, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)');
       const upsertEmb = db.prepare('INSERT OR REPLACE INTO pattern_embeddings (pattern_id, embedding) VALUES (?, ?)');
@@ -418,7 +467,9 @@ export async function importVectorsToAgentdb(
         }
         return imported;
       });
-      return { imported: commit() };
+      const imported = commit();
+      writeEmbedManifest(dbFile, currentEmbedManifest(model, guard.manifest.version, 'agentdb'));
+      return { imported };
     } finally {
       db.close();
     }
@@ -426,3 +477,61 @@ export async function importVectorsToAgentdb(
     return { imported: 0, error: `import failed: ${err instanceof Error ? err.message : String(err)}` };
   }
 }
+
+export async function reindexAgentdbRows(
+  projectRoot: string,
+  rows: readonly AgentdbRow[],
+  opts: { dbPath?: string; taskTypes?: readonly string[]; backupPath?: string } = {},
+): Promise<{ reembedded: number; model?: string; version?: number; backupPath?: string; error?: string }> {
+  const dbFile = resolveAgentdbPath(projectRoot, opts.dbPath);
+  const backupPath = opts.backupPath ?? `${dbFile}.pre-reindex-${Date.now()}.bak`;
+  if (existsSync(dbFile)) {
+    try {
+      const { copyFileSync } = await import('node:fs');
+      copyFileSync(dbFile, backupPath);
+      if (existsSync(`${dbFile}.embed-manifest.json`)) {
+        copyFileSync(`${dbFile}.embed-manifest.json`, `${backupPath}.embed-manifest.json`);
+      }
+    } catch (err) {
+      return { reembedded: 0, backupPath, error: `snapshot failed — reindex aborted: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  }
+  let sqliteUrl: string;
+  try {
+    const req = createRequire(join(projectRoot, 'package.json'));
+    sqliteUrl = pathToFileURL(req.resolve('better-sqlite3')).href;
+  } catch {
+    return { reembedded: 0, backupPath, error: DEPS_MISSING };
+  }
+  const model = resolveEmbedModel(projectRoot);
+  if ('error' in model) return { reembedded: 0, backupPath, error: model.error };
+  const oldVersion = readEmbedManifest(dbFile)?.version ?? 1;
+  try {
+    const { default: Database } = (await import(sqliteUrl)) as { default: new (p: string) => UpsertDb };
+    mkdirSync(dirname(dbFile), { recursive: true });
+    const db = new Database(dbFile);
+    try {
+      db.pragma('journal_mode = WAL');
+      db.pragma('busy_timeout = 5000');
+      db.exec(REASONING_BANK_SCHEMA);
+      const taskTypes = opts.taskTypes ?? DZ_TASK_TYPES;
+      const placeholders = taskTypes.map(() => '?').join(', ');
+      const delEmb = db.prepare(`DELETE FROM pattern_embeddings WHERE pattern_id IN (SELECT id FROM reasoning_patterns WHERE task_type IN (${placeholders}))`);
+      const delPat = db.prepare(`DELETE FROM reasoning_patterns WHERE task_type IN (${placeholders})`);
+      const tx = db.transaction(() => {
+        delEmb.run(...taskTypes);
+        delPat.run(...taskTypes);
+      });
+      tx();
+    } finally {
+      db.close();
+    }
+    const indexed = await indexPatternsToAgentdb(projectRoot, rows, { dbPath: dbFile });
+    if (indexed.error !== undefined) return { reembedded: 0, backupPath, error: indexed.error };
+    const version = Math.max(oldVersion + 1, 2);
+    writeEmbedManifest(dbFile, currentEmbedManifest(model, version, 'agentdb'));
+    return { reembedded: indexed.indexed, model: model.model, version, backupPath };
+  } catch (err) {
+    return { reembedded: 0, backupPath, error: `reindex failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}

package/src/brain.ts

@@ -17,11 +17,13 @@
 
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, type Dirent } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
 import { putBookKnowledge, queryBookKnowledge, bookKbPath, type BookKU, type BookKUHit } from './book-kb.js';
-import { indexPatternsToAgentdb, type AgentdbRow } from './agentdb-index.js';
+import { indexPatternsToAgentdb, searchAgentdbPatterns, reindexAgentdbRows, type AgentdbRow } from './agentdb-index.js';
+import { resolveEmbedModel, type EmbedModelConfig } from './embedding-config.js';
 
 // ─────────────────────────────────────── Home & paths ───────────────────────────────────────
 
@@ -783,6 +785,8 @@ const RERANK_PRIOR_BONUS = 0.5;
 
 /** Over-fetch cap for the rerank pass — bounds work while leaving room for a `limit*3` window. */
 const RERANK_OVERFETCH_CAP = 200;
+const GROUND_VECTOR_TIMEOUT_MS = 1_000;
+const GROUND_VECTOR_SIMILARITY_FLOOR = 0.35;
 
 /**
  * A DETERMINISTIC lexical reranker (ADR-001 §11 P3 / G3) — lifts precision on the top-K without a
@@ -855,6 +859,180 @@ export async function queryBrain(opts: {
   return { hits: rerankHits(opts.query, res.hits, { limit: effLimit }) };
 }
 
+async function bounded<T>(promise: Promise<T>, ms: number, fallback: () => T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise.catch(() => fallback()),
+      new Promise<T>((resolvePromise) => {
+        timer = setTimeout(() => resolvePromise(fallback()), ms);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+const backgroundWarmups = new Set<string>();
+
+function isFakeAgentdbForTests(depsRoot: string): boolean {
+  try {
+    const req = createRequire(join(depsRoot, 'package.json'));
+    const pkg = JSON.parse(readFileSync(req.resolve('agentdb/package.json'), 'utf-8')) as { version?: unknown };
+    return typeof pkg.version === 'string' && pkg.version.includes('test');
+  } catch {
+    return false;
+  }
+}
+
+function hasOnnxFile(dir: string, depth = 0, seen: { count: number } = { count: 0 }): boolean {
+  if (depth > 8 || seen.count > 2_000 || !existsSync(dir)) return false;
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    seen.count += 1;
+    const p = join(dir, entry.name);
+    if (entry.isFile() && entry.name.endsWith('.onnx')) return true;
+    if (entry.isDirectory() && hasOnnxFile(p, depth + 1, seen)) return true;
+    if (seen.count > 2_000) return false;
+  }
+  return false;
+}
+
+function cacheRoots(): string[] {
+  const roots: string[] = [];
+  const transformers = process.env['TRANSFORMERS_CACHE'];
+  if (transformers !== undefined && transformers !== '') roots.push(transformers);
+  const hfHome = process.env['HF_HOME'];
+  if (hfHome !== undefined && hfHome !== '') roots.push(join(hfHome, 'hub'));
+  const xdg = process.env['XDG_CACHE_HOME'];
+  roots.push(join(xdg !== undefined && xdg !== '' ? xdg : join(homedir(), '.cache'), 'huggingface', 'hub'));
+  return [...new Set(roots)];
+}
+
+function isEmbedModelCached(depsRoot: string, model: EmbedModelConfig): boolean {
+  if (isFakeAgentdbForTests(depsRoot)) return true;
+  const modelDir = `models--${model.model.replace(/\//g, '--')}`;
+  for (const root of cacheRoots()) {
+    if (hasOnnxFile(join(root, modelDir)) || hasOnnxFile(root.endsWith(modelDir) ? root : join(root, 'hub', modelDir))) return true;
+  }
+  return false;
+}
+
+function warmEmbedModelInBackground(depsRoot: string, model: EmbedModelConfig): void {
+  const key = `${depsRoot}\0${model.model}`;
+  if (backgroundWarmups.has(key)) return;
+  backgroundWarmups.add(key);
+  setImmediate(() => {
+    const script = `
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const root = ${JSON.stringify(depsRoot)};
+const model = ${JSON.stringify(model.model)};
+const dim = ${JSON.stringify(model.dim)};
+const req = createRequire(join(root, 'package.json'));
+const agentdbDir = dirname(req.resolve('agentdb'));
+const mod = await import(pathToFileURL(join(agentdbDir, 'controllers', 'EmbeddingService.js')).href);
+const emb = new mod.EmbeddingService({ model, dimension: dim, provider: 'transformers' });
+await emb.initialize();
+await emb.embed('warm embedding model cache');
+`;
+    try {
+      const nodeBin = existsSync(process.execPath) ? process.execPath : (process.argv[0] ?? 'node');
+      const child = spawn(nodeBin, ['--input-type=module', '-e', script], {
+        cwd: depsRoot,
+        detached: true,
+        stdio: ['ignore', 'ignore', 'ignore'],
+        env: { ...process.env, DZ_EMBED_MODEL: model.model },
+      });
+      child.on('error', () => undefined);
+      child.unref();
+    } catch {
+      /* warmup is advisory; the foreground grounding path must never block or throw */
+    }
+  });
+}
+
+export async function searchBrainVectors(opts: {
+  query: string;
+  brainHome?: string;
+  depsRoot?: string;
+  source?: string;
+  limit?: number;
+  timeoutMs?: number;
+}): Promise<{ hits: Array<BookKUHit & { similarity: number }>; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  const limit = Math.max(1, opts.limit ?? DEFAULT_QUERY_LIMIT);
+  const model = resolveEmbedModel(depsRoot);
+  if ('error' in model) return { hits: [], error: model.error };
+  if (!isEmbedModelCached(depsRoot, model)) {
+    // eslint-disable-next-line no-console
+    console.warn(`[dz brain] SKIP vector leg: embedding model cache is cold for ${model.model}; warming in background`);
+    warmEmbedModelInBackground(depsRoot, model);
+    return { hits: [], error: 'brain vector search skipped: embedding model cache cold' };
+  }
+  const run = async (): Promise<{ hits: Array<BookKUHit & { similarity: number }>; error?: string }> => {
+    const vec = await searchAgentdbPatterns(depsRoot, opts.query, {
+      dbPath: brainAgentdbPath(home),
+      taskTypes: ['book-knowledge'],
+      limit: limit * 3,
+      reindexHint: 'dz brain reindex',
+    });
+    if (vec.error !== undefined) return { hits: [], error: vec.error };
+    if (vec.hits.length === 0) return { hits: [] };
+    const read = readBookKus({ storePath: brainBooksPath(home), depsRoot, ...(opts.source !== undefined ? { source: opts.source } : {}) });
+    if (read.error !== undefined) return { hits: [], error: read.error };
+    const byKu = new Map(read.kus.map((ku) => [ku.kuId, ku]));
+    const hits: Array<BookKUHit & { similarity: number }> = [];
+    const seen = new Set<string>();
+    for (const h of vec.hits) {
+      if (h.dzId === undefined || seen.has(h.dzId)) continue;
+      const ku = byKu.get(h.dzId);
+      if (ku === undefined) continue;
+      seen.add(h.dzId);
+      hits.push({
+        book: ku.book,
+        kuId: ku.kuId,
+        type: ku.type,
+        name: ku.name,
+        problem: ku.problem,
+        content: ku.content,
+        ...(ku.chapter !== undefined ? { chapter: ku.chapter } : {}),
+        ...(ku.pages !== undefined ? { pages: ku.pages } : {}),
+        similarity: h.similarity,
+      });
+      if (hits.length >= limit) break;
+    }
+    return { hits };
+  };
+  return bounded(run(), opts.timeoutMs ?? GROUND_VECTOR_TIMEOUT_MS, () => ({ hits: [], error: 'brain vector search timed out' }));
+}
+
+export async function reindexBrainVectors(opts: {
+  brainHome?: string;
+  depsRoot?: string;
+}): Promise<{ reembedded: number; model?: string; version?: number; backupPath?: string; error?: string }> {
+  const home = opts.brainHome ?? brainHome();
+  const depsRoot = opts.depsRoot ?? process.cwd();
+  const read = readBookKus({ storePath: brainBooksPath(home), depsRoot });
+  if (read.error !== undefined) return { reembedded: 0, error: read.error };
+  const rows: AgentdbRow[] = read.kus.map((ku) => ({
+    taskType: 'book-knowledge',
+    text: `${ku.name}\n${ku.problem}\n${ku.content}`,
+    score: 1.0,
+    tags: ['book-knowledge', ku.book, ku.type],
+    metadata: { source: 'book-kb', book: ku.book, kuId: ku.kuId, dzId: ku.kuId, corpusVersion: ku.corpusVersion },
+  }));
+  return reindexAgentdbRows(depsRoot, rows, { dbPath: brainAgentdbPath(home), taskTypes: ['book-knowledge'] });
+}
+
 // ──────────────────────────────────────── Grounding ─────────────────────────────────────────
 
 /**
@@ -951,8 +1129,22 @@ export async function groundPrompt(opts: {
     const res = await queryBrain(query);
 
     // Gate 2: any lexical hit? On error or zero hits, stay silent (no noise, no block).
-    if (res.error !== undefined) return silent;
-    if (res.hits.length === 0) return silent;
+    const lexicalHits = res.error === undefined ? res.hits : [];
+    const semantic = await searchBrainVectors({
+      query: terms.join(' '),
+      limit: opts.k ?? 5,
+      ...(opts.brainHome !== undefined ? { brainHome: opts.brainHome } : {}),
+      ...(opts.depsRoot !== undefined ? { depsRoot: opts.depsRoot } : {}),
+      ...(opts.source !== undefined ? { source: opts.source } : {}),
+      timeoutMs: GROUND_VECTOR_TIMEOUT_MS,
+    });
+    const semanticHits = semantic.hits.filter((h) => h.similarity >= GROUND_VECTOR_SIMILARITY_FLOOR);
+    if (lexicalHits.length === 0 && semanticHits.length === 0) return silent;
+
+    const mergedByKu = new Map<string, BookKUHit>();
+    for (const h of lexicalHits) mergedByKu.set(h.kuId, h);
+    for (const h of semanticHits) if (!mergedByKu.has(h.kuId)) mergedByKu.set(h.kuId, h);
+    const merged = rerankHits(terms.join(' '), [...mergedByKu.values()], { limit: opts.k ?? 5 });
 
     // Gate 3 — COVERAGE (the OR balance): OR recall alone over-fires when a single common term
     // ("today", "data") incidentally matches a KU. Require the retrieved hits to actually cover the
@@ -961,20 +1153,20 @@ export async function groundPrompt(opts: {
     // off-topic prompt whose only matching word is incidental ("weather today" → only "today"
     // matches) stays silent, while a real one ("репликацию single multi leader" → 4 covered) grounds.
     if (terms.length >= 2) {
-      const hay = res.hits.map((h) => `${h.name} ${h.problem} ${h.content}`.toLowerCase()).join(' ');
+      const hay = lexicalHits.map((h) => `${h.name} ${h.problem} ${h.content}`.toLowerCase()).join(' ');
       const covered = terms.filter((t) => hay.includes(t.toLowerCase())).length;
-      if (covered < 2) return silent;
+      if (covered < 2 && semanticHits.length === 0) return silent;
     }
 
     // Build the GROUNDING DIRECTIVE block (§7.1): directive line + numbered citations.
     const lines: string[] = [GROUNDING_DIRECTIVE, ''];
-    res.hits.forEach((h, i) => {
+    merged.forEach((h, i) => {
       const ch = h.chapter !== undefined && h.chapter !== '' ? ` гл.${h.chapter}` : '';
       const pg = h.pages !== undefined && h.pages.length > 0 ? ` с.${h.pages.join('–')}` : '';
       const body = snippet(h.problem !== '' ? h.problem : h.content);
       lines.push(`[K${i + 1}] ${h.book}${ch}${pg} — ${h.name}: ${body}`);
     });
-    return { emitted: true, block: lines.join('\n'), hitCount: res.hits.length };
+    return { emitted: true, block: lines.join('\n'), hitCount: merged.length };
   } catch {
     // Grounding is advisory — a bug here must never surface to the user or block the prompt.
     return silent;

package/src/embedding-config.ts

@@ -0,0 +1,117 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export type EmbedModelSource = 'env' | 'config' | 'default';
+
+export interface EmbedModelConfig {
+  readonly model: string;
+  readonly dim: 384;
+  readonly source: EmbedModelSource;
+}
+
+export interface EmbedManifest {
+  readonly model: string;
+  readonly dim: 384;
+  readonly version: number;
+  readonly engine?: string;
+}
+
+export const DEFAULT_EMBED_MODEL = 'Xenova/paraphrase-multilingual-MiniLM-L12-v2';
+export const LEGACY_EMBED_MODEL = 'Xenova/all-MiniLM-L6-v2';
+export const DEFAULT_EMBED_DIM = 384;
+
+export const KNOWN_EMBED_DIMS: Readonly<Record<string, 384>> = {
+  [DEFAULT_EMBED_MODEL]: DEFAULT_EMBED_DIM,
+  [LEGACY_EMBED_MODEL]: DEFAULT_EMBED_DIM,
+  // e5 models require asymmetric "query:" / "passage:" prefixes at call sites to reach full quality.
+  'Xenova/multilingual-e5-small': DEFAULT_EMBED_DIM,
+  'Xenova/paraphrase-multilingual-mpnet-base-v2': DEFAULT_EMBED_DIM,
+};
+
+export function resolveEmbedModel(projectRoot: string): EmbedModelConfig | { error: string } {
+  const env = process.env['DZ_EMBED_MODEL'];
+  if (env !== undefined && env.trim() !== '') return modelConfig(env.trim(), 'env');
+  const cfgPath = join(projectRoot, '.dz', 'config.json');
+  if (existsSync(cfgPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')) as Record<string, unknown>;
+      const memory = cfg['memory'] as Record<string, unknown> | undefined;
+      const agentdb = memory?.['agentdb'] as Record<string, unknown> | undefined;
+      const embed = memory?.['embed'] as Record<string, unknown> | undefined;
+      const configured = agentdb?.['embeddingModel'] ?? embed?.['model'];
+      if (typeof configured === 'string' && configured.trim() !== '') return modelConfig(configured.trim(), 'config');
+    } catch {
+      /* corrupt config falls back to the default, matching the existing config-read discipline */
+    }
+  }
+  return modelConfig(DEFAULT_EMBED_MODEL, 'default');
+}
+
+function modelConfig(model: string, source: EmbedModelSource): EmbedModelConfig | { error: string } {
+  const dim = KNOWN_EMBED_DIMS[model];
+  if (dim === undefined) {
+    return { error: `unsupported embedding model '${model}' (known 384-dim models: ${Object.keys(KNOWN_EMBED_DIMS).join(', ')})` };
+  }
+  return { model, dim, source };
+}
+
+export function embedManifestPath(storePath: string): string {
+  return `${storePath}.embed-manifest.json`;
+}
+
+export function readEmbedManifest(storePath: string): EmbedManifest | undefined {
+  return readManifestFile(embedManifestPath(storePath));
+}
+
+function readManifestFile(p: string): EmbedManifest | undefined {
+  if (!existsSync(p)) return undefined;
+  try {
+    const m = JSON.parse(readFileSync(p, 'utf-8')) as Partial<EmbedManifest>;
+    if (typeof m.model !== 'string' || m.model === '') return undefined;
+    if (m.dim !== DEFAULT_EMBED_DIM) return undefined;
+    return { model: m.model, dim: DEFAULT_EMBED_DIM, version: typeof m.version === 'number' ? m.version : 1, ...(typeof m.engine === 'string' ? { engine: m.engine } : {}) };
+  } catch {
+    return undefined;
+  }
+}
+
+function readStoreManifest(storePath: string): EmbedManifest | undefined {
+  return readEmbedManifest(storePath) ?? readManifestFile(`${storePath}.manifest.json`);
+}
+
+export function writeEmbedManifest(storePath: string, manifest: EmbedManifest): void {
+  const p = embedManifestPath(storePath);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+export function legacyEmbedManifest(): EmbedManifest {
+  return { model: LEGACY_EMBED_MODEL, dim: DEFAULT_EMBED_DIM, version: 1 };
+}
+
+export function currentEmbedManifest(configured: EmbedModelConfig, version = 1, engine?: string): EmbedManifest {
+  return { model: configured.model, dim: configured.dim, version, ...(engine !== undefined ? { engine } : {}) };
+}
+
+export function guardEmbedSpace(args: {
+  storePath: string;
+  configured: EmbedModelConfig;
+  hasRows: boolean;
+  reindexHint: string;
+}): { ok: true; manifest: EmbedManifest } | { ok: false; error: string; manifest: EmbedManifest } {
+  const manifest = readStoreManifest(args.storePath)
+    ?? (args.hasRows ? legacyEmbedManifest() : currentEmbedManifest(args.configured));
+  if (manifest.model !== args.configured.model || manifest.dim !== args.configured.dim) {
+    return {
+      ok: false,
+      manifest,
+      error: `embedding model mismatch: index built with ${manifest.model}/${manifest.dim}, configured ${args.configured.model}/${args.configured.dim}; run ${args.reindexHint}`,
+    };
+  }
+  return { ok: true, manifest };
+}
+
+export function snapshotEmbedManifest(storePath: string, backupPath: string): void {
+  const p = embedManifestPath(storePath);
+  if (existsSync(p)) copyFileSync(p, backupPath);
+}