@dzhechkov/harness-core 0.3.84 → 0.3.88

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/skill-drift.ts

@@ -21,7 +21,7 @@
  */
 
 import { readdirSync, statSync, readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from 'node:fs';
-import { join, relative, dirname, basename } from 'node:path';
+import { join, relative, resolve, dirname, basename } from 'node:path';
 import { createHash } from 'node:crypto';
 
 /** One shared skill whose copies byte-differ (`driftFiles > 0`). */
@@ -65,27 +65,46 @@ export interface SweepResult {
   readonly allowlisted: readonly DriftedSkill[];
 }
 
+/**
+ * How the canonical was resolved for a {@link syncCanonicalSkill} run.
+ * - `from`        — an explicit `--from <dir>` was supplied.
+ * - `skills-meta` — no `--from`; `skills-meta/<skill>` exists and was used.
+ * - `auto`        — no explicit canonical; the WRITE path auto-detected the most-complete copy
+ *                   (opt-in `--auto` ONLY — never a bare default).
+ * - `none`        — no canonical could be resolved. `--check` still runs a canonical-free peer
+ *                   comparison; a bare write refuses (safe-by-default).
+ */
+export type CanonicalSource = 'from' | 'skills-meta' | 'auto' | 'none';
+
 /** Options for {@link syncCanonicalSkill}. */
 export interface SyncCanonicalOptions {
   /** Report drift only, write NOTHING (CI mode). */
   readonly check?: boolean;
   /** Override the canonical source dir (default: `skills-meta/<skill>`). */
   readonly from?: string;
+  /**
+   * Opt-in for the WRITE path ONLY: when no `--from`/`skills-meta` canonical exists, auto-detect the
+   * most-complete copy as canonical instead of refusing. A HEURISTIC — the CLI prints a loud warning
+   * naming the pick + the exact overwrite list. Never affects the read-only `check` path.
+   */
+  readonly auto?: boolean;
 }
 
-/** Result of a canonical-wins sync (or a `check:true` dry-run). */
+/** Result of a canonical-wins sync (or a `check:true` dry-run / canonical-free peer check). */
 export interface SyncResult {
-  /** Resolved canonical dir (abs). */
+  /** Resolved canonical dir (abs). Empty `''` in canonical-free peer / refuse modes. */
   readonly canonical: string;
-  /** Whether the canonical source dir exists. `false` ⇒ nothing was done (CLI → non-zero exit). */
+  /** Whether a canonical source dir was resolved. `false` ⇒ `resolvedFrom === 'none'`. */
   readonly canonicalExists: boolean;
-  /** # non-canonical copies found. */
+  /** How the canonical resolved: `from` | `skills-meta` | `auto` | `none`. */
+  readonly resolvedFrom: CanonicalSource;
+  /** # copies compared — non-canonical copies in resolved modes; ALL peers in canonical-free mode. */
   readonly copies: number;
-  /** # copies overwritten (0 when `check:true`). */
+  /** # copies overwritten (0 when `check:true`, in peer mode, or when a bare write refuses). */
   readonly synced: number;
-  /** # copies that differ from canonical. */
+  /** # copies/files that differ (from canonical in resolved modes; between peers in canonical-free mode). */
   readonly drifted: number;
-  /** Abs paths of copies written (empty when `check:true` — proves no writes). */
+  /** Abs paths of copies written (empty when `check:true` / peer / refuse — proves no writes). */
   readonly wrote: readonly string[];
 }
 
@@ -115,6 +134,69 @@ function walk(dir: string): string[] {
   return out;
 }
 
+/**
+ * Byte-compare a set of skill copies against EACH OTHER (canonical-free). Builds the union of
+ * relative file paths across every copy, hashes each `(copy × rel)`, and counts how many relative
+ * paths disagree (`driftFiles`) and how many `(copy × rel)` pairs are absent from a copy
+ * (`missingFiles`). `driftFiles > 0` ⇔ the copies are NOT byte-identical to one another.
+ *
+ * This is the exact per-skill comparison {@link sweepSkillDrift} performs; it is extracted verbatim
+ * so BOTH the CI sweep AND the canonical-free `sync-canonical --check` share one implementation and
+ * yield the same verdict. Behavior-preserving refactor — no numbers change.
+ */
+function comparePeers(copies: readonly string[]): { driftFiles: number; missingFiles: number; totalFiles: number } {
+  const relFiles = new Set<string>();
+  for (const c of copies) for (const f of walk(c)) relFiles.add(relative(c, f));
+
+  let driftFiles = 0;
+  let missingFiles = 0;
+  for (const rel of relFiles) {
+    const hashes = new Set<string>();
+    for (const c of copies) {
+      const p = join(c, rel);
+      if (existsSync(p)) hashes.add(md5(p));
+      else {
+        missingFiles++;
+        hashes.add('__MISSING__');
+      }
+    }
+    if (hashes.size > 1) driftFiles++;
+  }
+  return { driftFiles, missingFiles, totalFiles: relFiles.size };
+}
+
+/**
+ * Deterministic auto-pick of a canonical from a set of copies: the copy with the MOST files wins,
+ * tie-broken lexicographically on sorted path (so the same drift always auto-picks the same
+ * canonical, across runs and machines). "Most complete" is a HEURISTIC, not a correctness oracle —
+ * hence it is only ever reached behind an explicit `--auto` opt-in plus a loud warning.
+ */
+function pickMostComplete(copies: readonly string[]): string {
+  return [...copies].sort().reduce((best, c) => (walk(c).length > walk(best).length ? c : best));
+}
+
+/**
+ * Resolve WHICH dir is canonical for a sync/check run, and HOW it resolved. Precedence is identical
+ * for read and write paths:
+ *   1. `opts.from`            → `'from'`
+ *   2. `skills-meta/<skill>`  → `'skills-meta'`
+ *   3. `opts.auto` (write)    → `'auto'` (most-complete copy)
+ *   4. otherwise              → `'none'` (no canonical — `--check` compares copies to each other;
+ *                               a bare write refuses)
+ */
+function resolveCanonical(
+  root: string,
+  skill: string,
+  copies: readonly string[],
+  opts: SyncCanonicalOptions,
+): { canonical: string | null; resolvedFrom: CanonicalSource } {
+  if (opts.from !== undefined) return { canonical: resolve(opts.from), resolvedFrom: 'from' };
+  const meta = join(root, 'packages/@dzhechkov/skills-meta', skill);
+  if (existsSync(meta)) return { canonical: meta, resolvedFrom: 'skills-meta' };
+  if (opts.auto === true && copies.length >= 1) return { canonical: pickMostComplete(copies), resolvedFrom: 'auto' };
+  return { canonical: null, resolvedFrom: 'none' };
+}
+
 /**
  * Every skill dir (a dir containing `SKILL.md`) under `packages/` + `.claude/skills`, excluding
  * `node_modules` / `__pycache__`. Ported verbatim from `scripts/drift-sweep-skills.mjs`.
@@ -131,6 +213,10 @@ function findSkillDirs(root: string, scope: 'packages' | 'all' = 'all'): string[
     } catch {
       continue;
     }
+    // Drift-guard scope = SKILL.md-bearing dirs ONLY. `templates/docs/<name>/` mirrors carry
+    // skill-shaped NAMES but are rendered/derived documentation (no SKILL.md) and are therefore
+    // intentionally excluded — they are not skill definitions, so there is nothing to keep in sync.
+    // (Verified: no `packages/**/templates/docs/**` dir carries a SKILL.md. See ADR-001, D1.)
     if (entries.includes(SKILL_MANIFEST)) dirs.push(d);
     for (const e of entries) {
       if (IGNORED_ENTRIES.has(e)) continue;
@@ -173,31 +259,16 @@ export function sweepSkillDrift(root: string, opts: SweepOptions = {}): SweepRes
     duplicated++;
     const copies = [...unsorted].sort();
 
-    // Union of relative file paths across every copy.
-    const relFiles = new Set<string>();
-    for (const c of copies) for (const f of walk(c)) relFiles.add(relative(c, f));
-
-    let driftFiles = 0;
-    let missingFiles = 0;
-    for (const rel of relFiles) {
-      const hashes = new Set<string>();
-      for (const c of copies) {
-        const p = join(c, rel);
-        if (existsSync(p)) hashes.add(md5(p));
-        else {
-          missingFiles++;
-          hashes.add('__MISSING__');
-        }
-      }
-      if (hashes.size > 1) driftFiles++;
-    }
+    // Per-skill byte-comparison of every copy against each other (extracted to `comparePeers`
+    // so the canonical-free `sync-canonical --check` reuses the EXACT same logic).
+    const { driftFiles, missingFiles, totalFiles } = comparePeers(copies);
 
     if (driftFiles > 0) {
       const entry: DriftedSkill = {
         name,
         copies: copies.length,
         driftFiles,
-        totalFiles: relFiles.size,
+        totalFiles,
         missingFiles,
         locations: copies,
       };
@@ -212,31 +283,51 @@ export function sweepSkillDrift(root: string, opts: SweepOptions = {}): SweepRes
 }
 
 /**
- * Heal one skill: treat `from ?? skills-meta/<skill>` as canonical and overwrite every other copy in
- * the monorepo, proving byte-identity. Pure port of `scripts/sync-canonical-skill.mjs`.
+ * Heal one skill: treat the resolved canonical (`--from` → `skills-meta/<skill>` → `--auto`
+ * most-complete copy) as authoritative and overwrite every other copy in the monorepo, proving
+ * byte-identity. Pure port of `scripts/sync-canonical-skill.mjs`, extended with a canonical-free path.
  *
  * `check:true` writes NOTHING (`wrote` stays empty) and only reports the drift count.
  * Default overwrites drifting copies; a subsequent {@link sweepSkillDrift} then reports 0 drift.
- * When the canonical dir does not exist, returns `canonicalExists:false` and does nothing (the CLI
- * turns that into a non-zero exit) — this function never throws / never `process.exit`s.
+ *
+ * When NO canonical resolves (`resolvedFrom === 'none'` — no `--from`, no `skills-meta`, no `--auto`):
+ *   • `check:true` → CANONICAL-FREE peer check: `drifted` = # files that differ ACROSS the copies
+ *     (byte-identical copies ⇒ `drifted === 0`). Reuses {@link comparePeers} — the exact sweep logic.
+ *   • write (bare) → REFUSES: returns `wrote:[]`, `synced:0`, mutates NOTHING. Safe-by-default: the
+ *     tool never guesses a canonical for a write, because a wrong pick destroys the good copy. The
+ *     operator must pass `--from`, run `--check`, or opt in to `--auto` (which the CLI announces).
+ *
+ * This function never throws / never `process.exit`s — the CLI owns exit codes, printing, and the
+ * loud `--auto` warning.
  */
 export function syncCanonicalSkill(root: string, skill: string, opts: SyncCanonicalOptions = {}): SyncResult {
   const check = opts.check === true;
-  const canonical = opts.from ?? join(root, 'packages/@dzhechkov/skills-meta', skill);
 
-  if (!existsSync(canonical)) {
-    return { canonical, canonicalExists: false, copies: 0, synced: 0, drifted: 0, wrote: [] };
+  // The healer/checker operates on EXACTLY what the detector sees (same roots via findSkillDirs) —
+  // otherwise a copy could be silently healed but never gated, or vice-versa.
+  const allCopies = findSkillDirs(root, 'all')
+    .filter((d) => basename(d) === skill)
+    .sort();
+
+  const { canonical, resolvedFrom } = resolveCanonical(root, skill, allCopies, opts);
+
+  // No canonical resolved → asymmetric read/write handling (ADR-001 D3/D4).
+  if (canonical === null) {
+    if (check) {
+      // CANONICAL-FREE peer check: are the copies byte-identical to EACH OTHER? (<2 ⇒ vacuously so.)
+      const drifted = allCopies.length < 2 ? 0 : comparePeers(allCopies).driftFiles;
+      return { canonical: '', canonicalExists: false, resolvedFrom, copies: allCopies.length, synced: 0, drifted, wrote: [] };
+    }
+    // Bare WRITE with no resolvable canonical → REFUSE. Mutates nothing (`wrote:[]` proves it).
+    return { canonical: '', canonicalExists: false, resolvedFrom, copies: allCopies.length, synced: 0, drifted: 0, wrote: [] };
   }
 
   const canonFiles = walk(canonical)
     .map((p) => relative(canonical, p))
     .sort();
 
-  // The healer heals EXACTLY what the detector sees (same roots via findSkillDirs) — otherwise a copy
-  // could be silently healed but never gated, or vice-versa. Every <skill>/ dir except the canonical.
-  const copies = findSkillDirs(root, 'all')
-    .filter((d) => basename(d) === skill && relative(canonical, d) !== '')
-    .sort();
+  // Every <skill>/ dir except the canonical itself.
+  const copies = allCopies.filter((d) => relative(canonical, d) !== '');
 
   let drifted = 0;
   let synced = 0;
@@ -269,5 +360,5 @@ export function syncCanonicalSkill(root: string, skill: string, opts: SyncCanoni
     wrote.push(copy);
   }
 
-  return { canonical, canonicalExists: true, copies: copies.length, synced, drifted, wrote };
+  return { canonical, canonicalExists: true, resolvedFrom, copies: copies.length, synced, drifted, wrote };
 }

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