@dzhechkov/harness-core 0.3.86 → 0.3.88

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);
+}

package/src/index.ts

@@ -47,6 +47,7 @@ export {
   mergeHybridHits,
   recallHybrid,
   vectorTierStatus,
+  reindexVectorStore,
   harmonizeVectorStore,
   selectClusterKeeper,
   importRvfCheckpoint,
@@ -72,12 +73,15 @@ export type {
   HarmonizeOptions,
   ImportReport,
   ImportOptions,
+  ReindexVectorReport,
 } from './vector-tier.js';
 export { runSetup, generateHooksConfig, generateAgentdbWriter, writerVersionOf, AGENTDB_WRITER_VERSION } from './setup.js';
 export { statuslineData, readFeatureAdrState, writeFeatureAdrState, featureAdrStatePath } from './statusline.js';
 export type { StatuslineData, FeatureAdrState, WriteFeatureAdrStateInput } from './statusline.js';
-export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb } from './agentdb-index.js';
+export { indexPatternsToAgentdb, resolveAgentdbPath, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, reindexAgentdbRows } from './agentdb-index.js';
 export type { AgentdbSearchHit, AgentdbSearchResult, AgentdbImportRow } from './agentdb-index.js';
+export { DEFAULT_EMBED_MODEL, LEGACY_EMBED_MODEL, DEFAULT_EMBED_DIM, KNOWN_EMBED_DIMS, resolveEmbedModel, readEmbedManifest, writeEmbedManifest, embedManifestPath, legacyEmbedManifest } from './embedding-config.js';
+export type { EmbedModelConfig, EmbedModelSource, EmbedManifest } from './embedding-config.js';
 export { putBookKnowledge, queryBookKnowledge, bookKbPath } from './book-kb.js';
 export type { BookKU, BookKUHit } from './book-kb.js';
 export {
@@ -91,6 +95,8 @@ export {
   promoteProjectToBrain,
   updateBrainSource,
   queryBrain,
+  searchBrainVectors,
+  reindexBrainVectors,
   rerankHits,
   groundPrompt,
   buildPrimer,

package/src/setup.ts

@@ -271,7 +271,7 @@ function generateDzConfig(target: string, preset: string | undefined, backend: M
         mcpServer: 'agentdb',
         // Both the hook writer and the MCP server read/write THIS path (env AGENTDB_PATH).
         storePath: '.dz/agentdb.db',
-        embeddingModel: 'Xenova/all-MiniLM-L6-v2',
+        embeddingModel: 'Xenova/paraphrase-multilingual-MiniLM-L12-v2',
         sessionHookWrites: true,
       } : undefined,
     },

package/src/vector-tier.ts

@@ -59,7 +59,9 @@ import {
   resolveAgentdbEmbedder,
   cosineSimilarity,
   importVectorsToAgentdb,
+  reindexAgentdbRows,
 } from './agentdb-index.js';
+import { currentEmbedManifest, guardEmbedSpace, DEFAULT_EMBED_DIM, resolveEmbedModel, type EmbedModelConfig } from './embedding-config.js';
 
 /* ------------------------------------------------------------------ */
 /*  Types (04_domain_model §3.4 / §4.1)                                */
@@ -165,6 +167,7 @@ export interface VectorTierStatus {
   readonly kind?: VectorEngineKind | undefined;
   readonly available: boolean;
   readonly reason?: string | undefined;
+  readonly embeddingModel?: string | undefined;
   readonly lexicalTotal: number;
   readonly lexicalMirrorable: number;
   readonly mirrored?: number | undefined;
@@ -174,10 +177,6 @@ export interface VectorTierStatus {
 /** Wall-time bound applied to EVERY engine call, read and write legs alike (ADR R1 + NC1). */
 export const DEFAULT_VECTOR_TIMEOUT_MS = 10_000;
 
-/** The pinned local embedding model + dimension (agentdb's `EmbeddingService`; the RVF manifest space). */
-const LOCAL_EMBED_MODEL = 'Xenova/all-MiniLM-L6-v2';
-const LOCAL_EMBED_DIM = 384;
-
 /** Default cosine cutoff for near-duplicate clustering (`--threshold` / config overrides). */
 export const DEFAULT_HARMONIZE_THRESHOLD = 0.92;
 
@@ -255,6 +254,14 @@ export interface ImportOptions extends VectorServiceOptions {
   readonly embed?: ((text: string) => Promise<Float32Array>) | undefined;
 }
 
+export interface ReindexVectorReport {
+  readonly reembedded: number;
+  readonly model?: string;
+  readonly version?: number;
+  readonly backupPath?: string;
+  readonly error?: string;
+}
+
 /* ------------------------------------------------------------------ */
 /*  Timeout wrapper (both legs — NC1/QR-1)                             */
 /* ------------------------------------------------------------------ */
@@ -817,6 +824,7 @@ export async function vectorTierStatus(
   opts: VectorServiceOptions = {},
 ): Promise<VectorTierStatus> {
   const mode = readVectorEngineMode(projectRoot);
+  const model = resolveEmbedModel(projectRoot);
   let records: MemoryRecord[];
   try {
     records = loadStoreRecords(projectRoot);
@@ -831,6 +839,7 @@ export async function vectorTierStatus(
       mode,
       available: false,
       ...(resolved.reason !== undefined ? { reason: resolved.reason } : {}),
+      ...(!('error' in model) ? { embeddingModel: model.model } : {}),
       lexicalTotal: records.length,
       lexicalMirrorable,
       pending,
@@ -847,6 +856,7 @@ export async function vectorTierStatus(
     kind: engine.kind,
     available: true,
     ...(listed.error !== undefined ? { reason: listed.error } : {}),
+    ...(!('error' in model) ? { embeddingModel: model.model } : {}),
     lexicalTotal: records.length,
     lexicalMirrorable,
     mirrored: listed.error === undefined ? listed.ids.length : undefined,
@@ -854,6 +864,31 @@ export async function vectorTierStatus(
   };
 }
 
+export async function reindexVectorStore(projectRoot: string, opts: VectorServiceOptions = {}): Promise<ReindexVectorReport> {
+  const resolved = pickEngine(projectRoot, opts);
+  if (resolved.engine === undefined) return { reembedded: 0, error: resolved.reason ?? 'no vector engine available' };
+  if (resolved.engine.kind !== 'agentdb') {
+    return { reembedded: 0, error: 'dz vector reindex currently rewrites the agentdb learned-pattern mirror; switch memory.vector.engine to agentdb/auto' };
+  }
+  let records: MemoryRecord[];
+  try {
+    records = loadStoreRecords(projectRoot);
+  } catch {
+    records = [];
+  }
+  const rows = records
+    .map(memoryRecordVectorEntry)
+    .filter((r): r is VectorEntry => r !== undefined)
+    .map((r) => ({
+      taskType: r.taskType,
+      text: r.text,
+      score: r.score,
+      ...(r.tags !== undefined ? { tags: r.tags } : {}),
+      ...(r.metadata !== undefined ? { metadata: r.metadata } : {}),
+    }));
+  return reindexAgentdbRows(projectRoot, rows);
+}
+
 /* ------------------------------------------------------------------ */
 /*  Harmonize — SEMANTIC dedup of the lexical store (05 §2.1)          */
 /* ------------------------------------------------------------------ */
@@ -1139,8 +1174,15 @@ export async function importRvfCheckpoint(projectRoot: string, source: string, o
     if (existsSync(manifestPath)) {
       try {
         const m = JSON.parse(readFileSync(manifestPath, 'utf-8')) as { model?: unknown; dim?: unknown };
-        if ((typeof m.model === 'string' && m.model !== LOCAL_EMBED_MODEL) || (typeof m.dim === 'number' && m.dim !== LOCAL_EMBED_DIM)) {
-          return fail(`manifest mismatch: checkpoint (${String(m.model)}/${String(m.dim)}) ≠ local (${LOCAL_EMBED_MODEL}/${LOCAL_EMBED_DIM}) — refusing a cross-embedding-space merge`);
+        const configured = resolveEmbedModel(projectRoot);
+        if ('error' in configured) return fail(configured.error);
+        const manifest = {
+          model: typeof m.model === 'string' ? m.model : configured.model,
+          dim: typeof m.dim === 'number' ? m.dim : configured.dim,
+          version: 1,
+        };
+        if (manifest.model !== configured.model || manifest.dim !== configured.dim) {
+          return fail(`manifest mismatch: checkpoint (${String(manifest.model)}/${String(manifest.dim)}) ≠ local (${configured.model}/${configured.dim}) — run dz vector reindex; refusing a cross-embedding-space merge`);
         }
       } catch { /* unreadable manifest — tolerate; the idmap is the authority */ }
     }
@@ -1276,12 +1318,26 @@ function readRvfIdmap(projectRoot: string): RvfIdmap {
   }
 }
 
-function writeRvfSidecars(projectRoot: string, idmap: RvfIdmap): void {
+function guardRvfEmbedSpace(projectRoot: string, idmap: RvfIdmap): { ok: true; configured: EmbedModelConfig; version: number } | { ok: false; error: string } {
+  const configured = resolveEmbedModel(projectRoot);
+  if ('error' in configured) return { ok: false, error: configured.error };
+  const guard = guardEmbedSpace({
+    storePath: rvfBase(projectRoot),
+    configured,
+    hasRows: Object.keys(idmap.slots).length > 0,
+    reindexHint: 'dz vector reindex',
+  });
+  if (!guard.ok) return { ok: false, error: guard.error };
+  return { ok: true, configured, version: guard.manifest.version };
+}
+
+function writeRvfSidecars(projectRoot: string, idmap: RvfIdmap, configured: EmbedModelConfig, version: number): void {
   const base = rvfBase(projectRoot);
   mkdirSync(dirname(base), { recursive: true });
   writeFileSync(`${base}.idmap.json`, JSON.stringify(idmap, null, 2));
+  const manifest = currentEmbedManifest(configured, version, '@ruvector/rvf');
   writeFileSync(`${base}.manifest.json`, JSON.stringify(
-    { model: 'Xenova/all-MiniLM-L6-v2', dim: 384, engine: '@ruvector/rvf', version: 1 },
+    manifest,
     null,
     2,
   ));
@@ -1356,14 +1412,16 @@ function rvfVectorEngine(projectRoot: string): VectorEngine {
   return {
     kind: 'rvf',
     async upsert(entries) {
+      const idmap = readRvfIdmap(projectRoot);
+      const guard = guardRvfEmbedSpace(projectRoot, idmap);
+      if (!guard.ok) return { indexed: 0, error: guard.error };
       const emb = await resolveAgentdbEmbedder(projectRoot);
       if ('error' in emb) return { indexed: 0, error: noEmbedder };
       const loaded = await loadRvfModule(projectRoot);
       if (!loaded.ok) return { indexed: 0, error: loaded.error };
-      const store = await openRvfStore(loaded.mod, rvfBase(projectRoot), 384);
+      const store = await openRvfStore(loaded.mod, rvfBase(projectRoot), DEFAULT_EMBED_DIM);
       if ('error' in store) return { indexed: 0, error: store.error };
       try {
-        const idmap = readRvfIdmap(projectRoot);
         let indexed = 0;
         for (const e of entries) {
           const vec = await emb.embed(`${e.taskType}: ${e.text}`);
@@ -1372,7 +1430,7 @@ function rvfVectorEngine(projectRoot: string): VectorEngine {
           indexed += 1;
         }
         await store.close?.();
-        writeRvfSidecars(projectRoot, idmap);
+        writeRvfSidecars(projectRoot, idmap, guard.configured, guard.version);
         return { indexed };
       } catch (err) {
         return { indexed: 0, error: `rvf upsert failed: ${err instanceof Error ? err.message : String(err)}` };
@@ -1381,12 +1439,14 @@ function rvfVectorEngine(projectRoot: string): VectorEngine {
     async search(query, limit) {
       const emb = await resolveAgentdbEmbedder(projectRoot);
       if ('error' in emb) return { hits: [], error: noEmbedder };
+      const idmap = readRvfIdmap(projectRoot);
+      const guard = guardRvfEmbedSpace(projectRoot, idmap);
+      if (!guard.ok) return { hits: [], error: guard.error };
       const loaded = await loadRvfModule(projectRoot);
       if (!loaded.ok) return { hits: [], error: loaded.error };
-      const store = await openRvfStore(loaded.mod, rvfBase(projectRoot), 384);
+      const store = await openRvfStore(loaded.mod, rvfBase(projectRoot), DEFAULT_EMBED_DIM);
       if ('error' in store) return { hits: [], error: store.error };
       try {
-        const idmap = readRvfIdmap(projectRoot);
         const raw = await store.query(await emb.embed(query), limit);
         await store.close?.();
         const hits: VectorHit[] = [];
@@ -1410,12 +1470,14 @@ function rvfVectorEngine(projectRoot: string): VectorEngine {
       return { ids: [...new Set(Object.values(readRvfIdmap(projectRoot).slots))] };
     },
     async importVectors(rows) {
+      const idmap = readRvfIdmap(projectRoot);
+      const guard = guardRvfEmbedSpace(projectRoot, idmap);
+      if (!guard.ok) return { imported: 0, error: guard.error };
       const loaded = await loadRvfModule(projectRoot);
       if (!loaded.ok) return { imported: 0, error: loaded.error };
-      const store = await openRvfStore(loaded.mod, rvfBase(projectRoot), 384);
+      const store = await openRvfStore(loaded.mod, rvfBase(projectRoot), DEFAULT_EMBED_DIM);
       if ('error' in store) return { imported: 0, error: store.error };
       try {
-        const idmap = readRvfIdmap(projectRoot);
         let imported = 0;
         for (const r of rows) {
           await store.ingest(r.dzId, r.vector); // RVF ingest is upsert-by-id (id = dzId) — no duplicates
@@ -1423,7 +1485,7 @@ function rvfVectorEngine(projectRoot: string): VectorEngine {
           imported += 1;
         }
         await store.close?.();
-        writeRvfSidecars(projectRoot, idmap);
+        writeRvfSidecars(projectRoot, idmap, guard.configured, guard.version);
         return { imported };
       } catch (err) {
         return { imported: 0, error: `rvf import failed: ${err instanceof Error ? err.message : String(err)}` };