@dzhechkov/harness-core 0.3.86 → 0.3.90

package/src/feature-adr-routing.ts

@@ -0,0 +1,220 @@
+/**
+ * feature-adr per-stage model routing — the pure resolution core.
+ *
+ * This is the TESTABLE mirror of the routing block inlined into the
+ * `.claude/workflows/feature-adr.js` workflow (and its byte-identical
+ * skills-feature-adr template copy). The workflow is a top-level-`await`
+ * SCRIPT, not an importable module — the pipeline runs on import — so the
+ * pure helpers cannot be `import`-ed from it directly. Instead the workflow
+ * INLINES a byte-equivalent copy of the function bodies below, and
+ * `feature-adr-model-routing.test.ts` asserts the inline copy is
+ * string-equivalent to this module (a drift guard tying the tested code to
+ * the shipped code), then exercises these exports for the load-bearing
+ * behavioral assertions (LB-A/B/C, AC-1…AC-6).
+ *
+ * The load-bearing property: a model that WRITES code must not also SELF-QE.
+ * When `args.models.qe` is unset, the QE stage is auto-routed to the OTHER
+ * family than the resolved coder (codex-coder → Claude `opus`; Claude-coder →
+ * `codex:<top>:high`, or `opus` if codex is unavailable — never a block).
+ *
+ * DESIGN CONSTRAINT — the Workflow parser is STRICTER than `node --check`
+ * (no nested template literals, no inline `cond ? agent() : null` in arrays).
+ * The function BODIES here are written parser-safe (string `+` concat, explicit
+ * `if`/return, object-literal data tables) so the same source can be inlined
+ * verbatim into the workflow. Keep this module and the workflow's inline block
+ * in lock-step.
+ *
+ * @packageDocumentation
+ */
+
+/** A resolved `agent()` opts fragment: either a Claude `{model}` or a codex spec. */
+export interface StageOpts {
+  readonly model?: string;
+  readonly agentType?: string;
+  readonly codexModel?: string;
+  readonly _reasoning?: string;
+}
+
+/** The knobs `resolveStageModel` closes over — passed in from the workflow. */
+export interface RoutingEnv {
+  /** `args.models` — the per-stage override map (may be empty). */
+  readonly MODELS: Record<string, string | null | undefined>;
+  /** `args.codexModel` default id (default `'auto'`). */
+  readonly CODEX_MODEL: string;
+  /** Resolved legacy coder knob: `'claude' | 'codex' | 'codex-fallback'`. */
+  readonly CODER: string;
+  /** Resolved legacy qeReviewer knob: `'claude' | 'codex' | 'codex-fallback'`. */
+  readonly QE_REVIEWER: string;
+  /** `args.planner` shortcut (only `'codex'` is meaningful). */
+  readonly PLANNER?: string;
+  /**
+   * Whether codex is available at qe-resolution time. Defaults true; the caller
+   * passes `false` (from a pre-flight probe / `A.codexAvailable===false`) to force
+   * the cross-model QE default to fall back to a Claude reviewer instead of codex.
+   */
+  readonly codexAvailable?: boolean;
+  /** Optional log sink (the workflow passes its `log`); defaults to a no-op. */
+  readonly log?: (msg: string) => void;
+}
+
+// ── Data tables (data-only extensibility — gpt-5.6-ready) ───────────────────
+
+/** Known codex ids. Adding a new id (e.g. `'gpt-5.7'`) is a DATA-ONLY change. */
+export const KNOWN_CODEX: Record<string, number> = { auto: 1, 'gpt-5.5': 1, 'gpt-5.6': 1 };
+
+/** The Claude model names the Workflow runtime accepts as `agent()` `model`. */
+export const CLAUDE_NAMES: Record<string, number> = { fable: 1, opus: 1, sonnet: 1, haiku: 1 };
+
+/**
+ * The proven DEFAULT TABLE, applied only when the user opts into routing.
+ * `code`/`qe` are `null` SENTINELS: their defaults are DERIVED (the coder knob /
+ * the cross-model rule), not fixed model names.
+ */
+export const DEFAULT_MODELS: Record<string, string | null> = {
+  router: 'fable',
+  requirements: 'sonnet',
+  research: 'sonnet',
+  adr: 'opus',
+  ideation: 'sonnet',
+  ddd: 'opus',
+  architecture: 'opus',
+  plan: 'sonnet',
+  code: null,
+  qe: null,
+  fleet: 'sonnet',
+};
+
+// ── Pure resolvers (byte-equivalent to the workflow's inline block) ──────────
+
+/**
+ * Turn a compact model SPEC into `agent()` opts.
+ *   - falsy               → `{}`               (session-inherited — the BC path)
+ *   - `'codex[:id[:r]]'`  → `{agentType:'codex:codex-rescue', codexModel, _reasoning}`
+ *   - `'fable'|'opus'|…`  → `{model}`
+ *   - unknown             → warn + `{}` (Claude) / `CODEX_MODEL` (codex id)
+ */
+export function specToOpts(spec: string | null | undefined, env: RoutingEnv): StageOpts {
+  const log = env.log || function () {};
+  if (!spec) return {};
+  const parts = String(spec).split(':');
+  const head = parts[0] || '';
+  if (head === 'codex') {
+    let id = parts[1] || env.CODEX_MODEL;
+    if (id !== 'auto' && !KNOWN_CODEX[id]) {
+      log('models: unknown codex id ' + id + ' — using ' + env.CODEX_MODEL);
+      id = env.CODEX_MODEL;
+    }
+    const reasoning = parts[2] || 'high';
+    return { agentType: 'codex:codex-rescue', codexModel: id, _reasoning: reasoning };
+  }
+  if (CLAUDE_NAMES[head]) return { model: head };
+  log('models: unknown spec ' + spec + ' — session-inherited');
+  return {};
+}
+
+/**
+ * Fold the legacy `coder` knob into a spec:
+ *   `codex`/`codex-fallback` → `'codex:' + CODEX_MODEL + ':high'`; else `'opus'`.
+ * NOTE: a DIRECT `MODELS.code` spec bypasses this (handled in `resolveStageModel`);
+ * this only maps the KNOB, which is why `coderIsCodex` (below) also inspects `MODELS.code`.
+ */
+export function resolveCoderSpec(env: RoutingEnv): string {
+  if (env.CODER === 'codex' || env.CODER === 'codex-fallback') return 'codex:' + env.CODEX_MODEL + ':high';
+  return 'opus';
+}
+
+/**
+ * Whether the RESOLVED coder is the codex family — true when the coder knob is
+ * codex/codex-fallback OR a direct `MODELS.code` spec is a codex spec. The
+ * cross-model QE default derives from THIS (not the knob alone), so a direct
+ * `MODELS.code='codex'` still routes QE to Claude (never codex-self-QE).
+ */
+export function coderIsCodex(env: RoutingEnv): boolean {
+  if (env.CODER === 'codex' || env.CODER === 'codex-fallback') return true;
+  const codeSpec = env.MODELS.code;
+  if (codeSpec && String(codeSpec).split(':')[0] === 'codex') return true;
+  return false;
+}
+
+/**
+ * The CROSS-MODEL QE default (load-bearing). Called only when `MODELS.qe` is
+ * unset. Resolves to the OTHER family than the coder:
+ *   - coder is codex  → `'opus'`                       (Claude reviews codex's code)
+ *   - coder is Claude → codex-available ? `'codex:<top>:high'` : `'opus'` (never block)
+ * `<top>` = `CODEX_MODEL` when pinned (≠'auto'), else the top `KNOWN_CODEX` id.
+ */
+export function resolveQeSpec(env: RoutingEnv): string {
+  if (coderIsCodex(env)) return 'opus';
+  const CODEX_AVAILABLE = env.codexAvailable !== false;
+  if (!CODEX_AVAILABLE) return 'opus';
+  let top = env.CODEX_MODEL;
+  if (top === 'auto') {
+    const ids = Object.keys(KNOWN_CODEX);
+    for (let i = 0; i < ids.length; i++) {
+      if (ids[i] !== 'auto') top = ids[i] || top;
+    }
+  }
+  return 'codex:' + top + ':high';
+}
+
+/**
+ * Whether the caller opted into routing at all. When FALSE (no `args.models`,
+ * no codex knobs), every Claude stage resolves to `{}` → byte-identical to today.
+ */
+export function routingRequested(env: RoutingEnv): boolean {
+  return (
+    Object.keys(env.MODELS).length > 0 ||
+    env.PLANNER === 'codex' ||
+    env.CODER === 'codex' ||
+    env.CODER === 'codex-fallback' ||
+    env.QE_REVIEWER === 'codex' ||
+    env.QE_REVIEWER === 'codex-fallback'
+  );
+}
+
+/**
+ * Whether the Step-8 QE reviewer should be CODEX. This is the load-bearing cross-model gate — it must
+ * NEVER let the model that wrote the code also self-QE. Order:
+ *   1. an explicit `MODELS.qe` spec wins outright (user opt-in — even a codex qe against a codex coder).
+ *   2. else the legacy `QE_REVIEWER==='codex'` knob asks for codex, but is HONORED ONLY when the coder is
+ *      NOT codex — a codex coder + `qeReviewer:'codex'` would be codex-self-QE (the anti-pattern this whole
+ *      feature exists to prevent), so cross-model wins and QE stays Claude.
+ *   3. else fall to the cross-model DEFAULT (`resolveQeSpec`): codex iff the coder is Claude & codex is
+ *      available & routing was opted into. No routing → false → today's Claude QE (byte-identical BC).
+ * NOTE: the previous inline gate re-added `QE_REVIEWER==='codex'` AFTER the safe resolver, so a codex
+ * coder with the legacy knob silently self-QE'd. This function is the single tested source of that truth.
+ */
+export function qeShouldUseCodex(env: RoutingEnv): boolean {
+  const explicit = env.MODELS.qe;
+  if (explicit !== undefined && explicit !== null) {
+    return String(explicit).split(':')[0] === 'codex';
+  }
+  if (env.QE_REVIEWER === 'codex') return !coderIsCodex(env);
+  return routingRequested(env) && resolveQeSpec(env).split(':')[0] === 'codex';
+}
+
+/**
+ * Resolve a stage to its `agent()` opts fragment.
+ *   1. explicit `MODELS[stage]` wins
+ *   2. else if the user did NOT opt into routing → `{}` (byte-identical BC path)
+ *   3. else the DEFAULT TABLE fills the gap
+ *   4. `code`/`qe` `null` sentinels resolve via the coder / cross-model rules
+ */
+export function resolveStageModel(stage: string, env: RoutingEnv): StageOpts {
+  let spec = env.MODELS[stage];
+  if (spec === undefined) {
+    if (!routingRequested(env)) return {};
+    spec = DEFAULT_MODELS[stage];
+  }
+  if (stage === 'code' && (spec === null || spec === undefined)) return specToOpts(resolveCoderSpec(env), env);
+  if (stage === 'qe' && (spec === null || spec === undefined)) return specToOpts(resolveQeSpec(env), env);
+  return specToOpts(spec, env);
+}
+
+/** Spread-merge a resolved opts fragment onto a call's base opts (extra wins). */
+export function mergeOpts<B extends object, E extends object>(base: B, extra: E): B & E {
+  const out: Record<string, unknown> = {};
+  for (const k in base) out[k] = (base as Record<string, unknown>)[k];
+  for (const k in extra) out[k] = (extra as Record<string, unknown>)[k];
+  return out as B & E;
+}

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,
@@ -161,3 +167,16 @@ export type {
 } from './mcp-scan.js';
 export type { RegistryEntry, Registry } from './registry.js';
 export type { BenchmarkCheck, BenchmarkScore, BenchmarkReport, CompareResult } from './benchmark.js';
+export {
+  specToOpts,
+  resolveStageModel,
+  resolveCoderSpec,
+  coderIsCodex,
+  resolveQeSpec,
+  routingRequested,
+  mergeOpts,
+  DEFAULT_MODELS,
+  KNOWN_CODEX,
+  CLAUDE_NAMES,
+} from './feature-adr-routing.js';
+export type { StageOpts, RoutingEnv } from './feature-adr-routing.js';

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