@dzhechkov/harness-core 0.3.78 → 0.3.82

package/src/vector-tier.ts

@@ -33,7 +33,7 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, renameSync, appendFileSync, copyFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 
@@ -47,10 +47,19 @@ import {
   patternIdentityOf,
   dreamRecordId,
   loadStoreRecords,
+  removePatternsByIds,
+  snapshotStore,
   type PatternRecord,
   type RecallHit,
 } from './patterns.js';
-import { indexPatternsToAgentdb, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder } from './agentdb-index.js';
+import {
+  indexPatternsToAgentdb,
+  searchAgentdbPatterns,
+  listAgentdbDzIds,
+  resolveAgentdbEmbedder,
+  cosineSimilarity,
+  importVectorsToAgentdb,
+} from './agentdb-index.js';
 
 /* ------------------------------------------------------------------ */
 /*  Types (04_domain_model §3.4 / §4.1)                                */
@@ -96,6 +105,16 @@ export interface MirrorReceipt {
   readonly error?: string | undefined;
 }
 
+/** One precomputed vector to upsert by its content-addressed `dzId` (the `dz vector import` row). */
+export interface ImportVectorRow {
+  readonly dzId: string;
+  readonly vector: Float32Array;
+  readonly text: string;
+  readonly taskType: string;
+  readonly score: number;
+  readonly metadata?: Record<string, unknown> | undefined;
+}
+
 /** The engine PORT — both adapters implement exactly this surface (04 §4.1). */
 export interface VectorEngine {
   readonly kind: VectorEngineKind;
@@ -104,6 +123,12 @@ export interface VectorEngine {
   listIds(): Promise<{ ids: string[]; error?: string | undefined }>;
   /** Portable single-file checkpoint (RVF adapter only — `dz vector export`). */
   exportCheckpoint?(dest: string): Promise<{ error?: string | undefined }>;
+  /**
+   * Write precomputed `{ dzId, vector }` rows by id (`dz vector import`) — UPSERT-BY-dzId, never a
+   * blind whole-store overwrite. Optional (like {@link VectorEngine.exportCheckpoint}): an engine
+   * that cannot take a precomputed vector reports an honest reason; import degrades, never throws.
+   */
+  importVectors?(rows: readonly ImportVectorRow[]): Promise<{ imported: number; error?: string | undefined }>;
 }
 
 /** Outcome of {@link resolveVectorEngine}: an engine, or an honest reason why not. */
@@ -149,6 +174,87 @@ 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;
+
+/* ------------------------------------------------------------------ */
+/*  Harmonize + import types (dz-vector-harmonize-import 05 §2.1/§2.2)  */
+/* ------------------------------------------------------------------ */
+
+/** One record in the harmonize pool — a lexical-store record mapped to its dzId + reward + ts. */
+export interface HarmonizeItem {
+  readonly dzId: string;
+  readonly text: string;
+  readonly reward: number;
+  readonly ts: string;
+  readonly taskType: string;
+}
+
+/** One near-duplicate cluster: the surviving keeper + the members that would be / were dropped. */
+export interface HarmonizeCluster {
+  readonly keep: { readonly dzId: string; readonly text: string; readonly reward: number; readonly ts: string };
+  readonly drops: readonly { readonly dzId: string; readonly text: string; readonly reward: number; readonly cos: number }[];
+}
+
+/** Outcome of {@link harmonizeVectorStore}. */
+export interface HarmonizeReport {
+  readonly mode: 'dry-run' | 'apply';
+  /** Resolved engine kind, or `'none'` when there is no engine. */
+  readonly engine: string;
+  /** True when semantic dedup was unavailable and the store was harmonized by EXACT text only. */
+  readonly fellBackToExact: boolean;
+  readonly threshold: number;
+  readonly clusters: readonly HarmonizeCluster[];
+  /** Number of clusters (size ≥ 2) — one keeper survives per cluster. */
+  readonly kept: number;
+  /** Total non-keeper members (previewed in dry-run, removed on `--apply`). */
+  readonly dropped: number;
+  /** Singleton (non-duplicate) patterns — NEVER touched. */
+  readonly unique: number;
+  /** Backup path written before an `--apply` drop (restorable via `dz teach --from-json`). */
+  readonly backupPath?: string | undefined;
+  /** Honest reason on failure (e.g. a backup write failed and the drop was aborted). */
+  readonly error?: string | undefined;
+}
+
+/** Options for {@link harmonizeVectorStore}. */
+export interface HarmonizeOptions extends VectorServiceOptions {
+  /** Perform the drop (default `false` — dry-run previews and writes nothing). */
+  readonly apply?: boolean | undefined;
+  /** Cosine cutoff in `(0, 1]`; overrides config + the {@link DEFAULT_HARMONIZE_THRESHOLD} default. */
+  readonly threshold?: number | undefined;
+  /**
+   * Inject an embedder (tests): a function ⇒ semantic path with these embeddings; `null` ⇒ force the
+   * exact-text fallback; `undefined` ⇒ resolve the project's agentdb embedder.
+   */
+  readonly embed?: ((text: string) => Promise<Float32Array>) | null | undefined;
+}
+
+/** Outcome of {@link importRvfCheckpoint}. */
+export interface ImportReport {
+  /** Vectors upserted by dzId (new + replaced). */
+  readonly imported: number;
+  /** Source dzIds skipped because no local pattern exists (text must be imported first). */
+  readonly skippedOrphans: number;
+  /** Resolved target engine kind, or `'none'`. */
+  readonly engine: string;
+  /** The source `.rvf` path. */
+  readonly source: string;
+  readonly error?: string | undefined;
+}
+
+/** Options for {@link importRvfCheckpoint}. */
+export interface ImportOptions extends VectorServiceOptions {
+  /** Inject the source `{ dzId, vector }` rows (tests) — bypasses the `.rvf`/idmap file reads. */
+  readonly sourceRows?: readonly { readonly dzId: string; readonly vector: Float32Array }[] | undefined;
+  /** Inject an embedder (tests) for the local-text re-embed; else the project's agentdb embedder. */
+  readonly embed?: ((text: string) => Promise<Float32Array>) | undefined;
+}
+
 /* ------------------------------------------------------------------ */
 /*  Timeout wrapper (both legs — NC1/QR-1)                             */
 /* ------------------------------------------------------------------ */
@@ -265,6 +371,22 @@ export function readVectorEngineMode(projectRoot: string): VectorEngineMode {
   }
 }
 
+/**
+ * Read `memory.vector.harmonizeThreshold` from `.dz/config.json`. Absent/corrupt/out-of-range ⇒
+ * {@link DEFAULT_HARMONIZE_THRESHOLD} (never throws). `--threshold` overrides this at the call site.
+ */
+export function readHarmonizeThreshold(projectRoot: string): number {
+  try {
+    const cfg = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8')) as {
+      memory?: { vector?: { harmonizeThreshold?: unknown } };
+    };
+    const t = cfg.memory?.vector?.harmonizeThreshold;
+    return typeof t === 'number' && t > 0 && t <= 1 ? t : DEFAULT_HARMONIZE_THRESHOLD;
+  } catch {
+    return DEFAULT_HARMONIZE_THRESHOLD;
+  }
+}
+
 /**
  * Should `dz teach` attempt the best-effort vector mirror at all? True when the project opted
  * into the agentdb memory backend (`memory.backend === 'agentdb'`, the same gate consolidate
@@ -732,6 +854,352 @@ export async function vectorTierStatus(
   };
 }
 
+/* ------------------------------------------------------------------ */
+/*  Harmonize — SEMANTIC dedup of the lexical store (05 §2.1)          */
+/* ------------------------------------------------------------------ */
+
+/** Bounded, honest embed of one text — a throw/timeout surfaces as `{ error }`, never propagates. */
+async function boundedEmbed(
+  embed: (text: string) => Promise<Float32Array>,
+  text: string,
+  timeoutMs: number,
+): Promise<Float32Array | { error: string }> {
+  return withVectorTimeout(
+    safeEngineCall<Float32Array | { error: string }>(() => embed(text), (m) => ({ error: m })),
+    timeoutMs,
+    () => ({ error: 'embed timed out' }),
+  );
+}
+
+/**
+ * Deterministic keeper INDEX within a near-dup cluster (a TOTAL order over fixed inputs — NFR-7):
+ * (1) highest reward → (2) longer / more-specific text → (3) newer `ts` → (4) `dzId` (stable
+ * final tiebreak). Pure — no I/O. The keeper survives; the other members are the drop set.
+ */
+export function selectClusterKeeper(members: readonly HarmonizeItem[]): number {
+  let best = 0;
+  for (let i = 1; i < members.length; i += 1) {
+    if (isBetterKeeper(members[i]!, members[best]!)) best = i;
+  }
+  return best;
+}
+
+function isBetterKeeper(a: HarmonizeItem, b: HarmonizeItem): boolean {
+  if (a.reward !== b.reward) return a.reward > b.reward; // (1) highest reward
+  if (a.text.length !== b.text.length) return a.text.length > b.text.length; // (2) longer / more specific
+  if (a.ts !== b.ts) return a.ts > b.ts; // (3) newer
+  return a.dzId < b.dzId; // (4) stable, deterministic final tiebreak
+}
+
+/** Connected components over undirected `edges` (union-find) — transitive clusters (A~B,B~C ⇒ {A,B,C}). */
+function connectedComponents(n: number, edges: readonly (readonly [number, number])[]): number[][] {
+  const parent = Array.from({ length: n }, (_, i) => i);
+  const find = (x: number): number => {
+    let r = x;
+    while (parent[r] !== r) r = parent[r]!;
+    while (parent[x] !== r) {
+      const next = parent[x]!;
+      parent[x] = r;
+      x = next;
+    }
+    return r;
+  };
+  for (const [a, b] of edges) {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) parent[ra] = rb;
+  }
+  const groups = new Map<number, number[]>();
+  for (let i = 0; i < n; i += 1) {
+    const r = find(i);
+    const g = groups.get(r);
+    if (g === undefined) groups.set(r, [i]);
+    else g.push(i);
+  }
+  return [...groups.values()];
+}
+
+/** Build a {@link HarmonizeCluster} from a component's item indices + keeper's cosine to each drop. */
+function buildCluster(
+  items: readonly HarmonizeItem[],
+  indices: readonly number[],
+  cosToKeeper: (dropIdx: number, keeperIdx: number) => number,
+): HarmonizeCluster {
+  const members = indices.map((i) => items[i]!);
+  const keeperIdx = indices[selectClusterKeeper(members)]!;
+  const keeper = items[keeperIdx]!;
+  const drops = indices
+    .filter((i) => i !== keeperIdx)
+    .map((i) => ({ dzId: items[i]!.dzId, text: items[i]!.text, reward: items[i]!.reward, cos: cosToKeeper(i, keeperIdx) }));
+  return { keep: { dzId: keeper.dzId, text: keeper.text, reward: keeper.reward, ts: keeper.ts }, drops };
+}
+
+/** Semantic clusters: pairwise cosine ≥ θ (i<j) ⇒ union-find edge; components of size ≥ 2 are clusters. */
+function semanticClusters(items: readonly HarmonizeItem[], vecs: readonly Float32Array[], threshold: number): HarmonizeCluster[] {
+  const n = items.length;
+  const edges: [number, number][] = [];
+  for (let i = 0; i < n; i += 1) {
+    for (let j = i + 1; j < n; j += 1) {
+      if (cosineSimilarity(vecs[i]!, vecs[j]!) >= threshold) edges.push([i, j]);
+    }
+  }
+  const clusters: HarmonizeCluster[] = [];
+  for (const comp of connectedComponents(n, edges)) {
+    if (comp.length < 2) continue;
+    clusters.push(buildCluster(items, comp, (d, k) => cosineSimilarity(vecs[d]!, vecs[k]!)));
+  }
+  return clusters;
+}
+
+/** Exact-text fallback: group by RAW pattern text (the identity `teach --from-json` dedups on); cos = 1.0. */
+function exactClusters(items: readonly HarmonizeItem[]): HarmonizeCluster[] {
+  const byText = new Map<string, number[]>();
+  items.forEach((it, i) => {
+    const g = byText.get(it.text);
+    if (g === undefined) byText.set(it.text, [i]);
+    else g.push(i);
+  });
+  const clusters: HarmonizeCluster[] = [];
+  for (const indices of byText.values()) {
+    if (indices.length < 2) continue;
+    clusters.push(buildCluster(items, indices, () => 1.0));
+  }
+  return clusters;
+}
+
+/** Honest note next to the session telemetry (mirrors {@link logMirrorNote}). */
+function logHarmonizeNote(projectRoot: string, info: { dropped: number; kept: number; engine: string; error?: string | undefined }): void {
+  try {
+    appendFileSync(
+      join(projectRoot, '.dz', 'sessions.jsonl'),
+      JSON.stringify({ event: 'harmonize', ts: new Date().toISOString(), ...info }) + '\n',
+    );
+  } catch { /* best-effort */ }
+}
+
+/**
+ * SEMANTIC dedup of the learned-pattern store (`dz vector harmonize` / `dz teach --harmonize`) —
+ * **NON-DESTRUCTIVE by contract**. Finds near-duplicate PAIRS via pairwise cosine over the embedder
+ * both adapters share (θ default {@link DEFAULT_HARMONIZE_THRESHOLD}), union-finds them into clusters,
+ * and within each cluster KEEPs the highest-signal member ({@link selectClusterKeeper}), dropping the
+ * rest. Modes:
+ *
+ * - **dry-run (default)**: previews the clusters and returns — writes NOTHING (the store is
+ *   byte-identical after).
+ * - **`--apply`**: writes a restorable backup FIRST (`.dz/memory/patterns.pre-harmonize.json`); a
+ *   failed backup ABORTS the drop (no partial mutation). Then removes the non-keepers from BOTH
+ *   lexical tiers via {@link removePatternsByIds}. A UNIQUE (singleton) pattern is NEVER a drop.
+ *
+ * Degrades honestly: with no engine/embedder it falls back to EXACT-text dedup + a `fellBackToExact`
+ * note, exits without throwing (dry-run still writes nothing). Reversal: `dz teach --from-json <backup>`.
+ */
+export async function harmonizeVectorStore(projectRoot: string, opts: HarmonizeOptions = {}): Promise<HarmonizeReport> {
+  const apply = opts.apply === true;
+  const threshold =
+    opts.threshold !== undefined && opts.threshold > 0 && opts.threshold <= 1
+      ? opts.threshold
+      : readHarmonizeThreshold(projectRoot);
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_VECTOR_TIMEOUT_MS;
+
+  // 1. LOAD the pool from the lexical source of truth (id = dzId).
+  let records: MemoryRecord[];
+  try {
+    records = loadStoreRecords(projectRoot);
+  } catch {
+    records = [];
+  }
+  const items: HarmonizeItem[] = records.map((r) => ({
+    dzId: r.id,
+    text: r.text,
+    reward: r.score,
+    ts: r.timestamp,
+    taskType: r.id.startsWith('dream:') ? 'dz-learning' : 'dz-teach',
+  }));
+
+  // 2. GATE: an embedder ⇒ SEMANTIC clustering; absence/failure ⇒ EXACT-text fallback (D4).
+  let embed: ((text: string) => Promise<Float32Array>) | undefined;
+  let engineKind = 'none';
+  let fellBackToExact = false;
+  if (opts.embed === null) {
+    fellBackToExact = true;
+  } else if (opts.embed !== undefined) {
+    embed = opts.embed;
+    engineKind = 'agentdb';
+  } else {
+    const resolved = pickEngine(projectRoot, opts);
+    if (resolved.engine === undefined) {
+      fellBackToExact = true;
+    } else {
+      engineKind = resolved.engine.kind;
+      const emb = await resolveAgentdbEmbedder(projectRoot);
+      if ('error' in emb) fellBackToExact = true;
+      else embed = (t) => emb.embed(t);
+    }
+  }
+
+  // 3. CLUSTER (nothing to cluster ⇒ no clusters, everything unique).
+  let clusters: HarmonizeCluster[] | undefined;
+  if (items.length >= 2 && !fellBackToExact && embed !== undefined) {
+    const vecs: Float32Array[] = [];
+    let ok = true;
+    for (const it of items) {
+      const v = await boundedEmbed(embed, `${it.taskType}: ${it.text}`, timeoutMs);
+      if (!(v instanceof Float32Array)) {
+        ok = false;
+        break;
+      }
+      vecs.push(v);
+    }
+    if (ok) clusters = semanticClusters(items, vecs, threshold);
+    else fellBackToExact = true; // embed failed/timed out — fall back to exact
+  }
+  if (clusters === undefined) {
+    fellBackToExact = fellBackToExact || embed === undefined;
+    clusters = items.length >= 2 ? exactClusters(items) : [];
+  }
+
+  // 4. TOTALS (a unique = a singleton; never a member of a drop set).
+  const dropDzIds = new Set<string>();
+  for (const c of clusters) for (const d of c.drops) dropDzIds.add(d.dzId);
+  const kept = clusters.length;
+  const dropped = dropDzIds.size;
+  const unique = items.length - kept - dropped;
+  const base: HarmonizeReport = {
+    mode: apply ? 'apply' : 'dry-run',
+    engine: engineKind,
+    fellBackToExact,
+    threshold,
+    clusters,
+    kept,
+    dropped,
+    unique,
+  };
+
+  // 5a. DRY-RUN (default): return — ZERO writes (the store is byte-identical after).
+  if (!apply) return base;
+
+  // 5b. --apply: BACKUP FIRST, then drop the non-keepers. Nothing to drop ⇒ no backup, no mutation.
+  if (dropped === 0) {
+    logHarmonizeNote(projectRoot, { dropped: 0, kept, engine: engineKind });
+    return base;
+  }
+  const backupPath = join(projectRoot, '.dz', 'memory', 'patterns.pre-harmonize.json');
+  const snap = snapshotStore(projectRoot, backupPath);
+  if (snap.error !== undefined) {
+    // Backup write failed ⇒ ABORT the drop (no partial mutation — the store is untouched).
+    return { ...base, error: `backup failed — drop aborted: ${snap.error}` };
+  }
+  const removal = removePatternsByIds(projectRoot, dropDzIds);
+  logHarmonizeNote(projectRoot, { dropped: removal.removed, kept, engine: engineKind, error: removal.error });
+  return { ...base, backupPath, ...(removal.error !== undefined ? { error: removal.error } : {}) };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Import — RVF checkpoint ingest, UPSERT-BY-dzId (05 §2.2)           */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Ingest an external `.rvf` checkpoint's vectors into THIS project's vector store, **UPSERT-BY-dzId,
+ * NON-DESTRUCTIVE** (`dz vector import <file.rvf>`). The `.idmap.json` sidecar is the dzId authority
+ * (the shipped `@ruvector/rvf` SDK exposes no vector read-out — see rUv `rvf-backend-blocker.md`), so
+ * for each checkpoint dzId that exists in the LOCAL lexical store the vector is reproduced by
+ * re-embedding the local text (D7 — under the manifest guard the same model over the same text yields
+ * the checkpoint's vector) and upserted by dzId via {@link VectorEngine.importVectors}. dzIds absent
+ * locally are ORPHANS — skipped + counted (their text must be imported first via `dz teach --from-json`).
+ *
+ * Non-destructive: only the imported dzIds are inserted/replaced; re-importing the same file adds 0
+ * duplicates and deletes nothing. A model/dim manifest mismatch is REFUSED (no cross-space merge). All
+ * failure modes return an honest `{ error }`, never a throw.
+ */
+export async function importRvfCheckpoint(projectRoot: string, source: string, opts: ImportOptions = {}): Promise<ImportReport> {
+  const fail = (error: string, engine = 'none'): ImportReport => ({ imported: 0, skippedOrphans: 0, engine, source, error });
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_VECTOR_TIMEOUT_MS;
+
+  // 1. Source dzIds: the `.idmap.json` sidecar (dzId authority) — or injected rows (tests).
+  const injected = new Map<string, Float32Array>();
+  let sourceDzIds: string[];
+  if (opts.sourceRows !== undefined) {
+    for (const r of opts.sourceRows) injected.set(r.dzId, r.vector);
+    sourceDzIds = [...injected.keys()];
+  } else {
+    if (!existsSync(source)) return fail(`no such file: ${source}`);
+    const idmapPath = `${source}.idmap.json`;
+    if (!existsSync(idmapPath)) {
+      return fail(`missing sidecar ${basename(idmapPath)} — export writes it next to the .rvf (re-run: dz vector export)`);
+    }
+    let idmap: RvfIdmap;
+    try {
+      const parsed = JSON.parse(readFileSync(idmapPath, 'utf-8')) as RvfIdmap;
+      idmap = typeof parsed === 'object' && parsed !== null && typeof parsed.slots === 'object' ? parsed : { version: 1, slots: {} };
+    } catch {
+      return fail(`unreadable idmap sidecar: ${basename(idmapPath)}`);
+    }
+    // Manifest guard (R-i1): refuse a foreign embedding model/dim — no silent cross-space merge.
+    const manifestPath = `${source}.manifest.json`;
+    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`);
+        }
+      } catch { /* unreadable manifest — tolerate; the idmap is the authority */ }
+    }
+    sourceDzIds = [...new Set(Object.values(idmap.slots))];
+  }
+
+  // 2. Resolve the TARGET engine (agentdb default, or rvf if configured).
+  const resolved = pickEngine(projectRoot, opts);
+  if (resolved.engine === undefined) return fail(resolved.reason ?? 'no vector engine available');
+  const engine = resolved.engine;
+  if (engine.importVectors === undefined) {
+    return { imported: 0, skippedOrphans: 0, engine: engine.kind, source, error: `the ${engine.kind} engine cannot import precomputed vectors` };
+  }
+
+  // 3. ORPHAN GATE against the lexical source of truth.
+  let records: MemoryRecord[];
+  try {
+    records = loadStoreRecords(projectRoot);
+  } catch {
+    records = [];
+  }
+  const byId = new Map<string, MemoryRecord>();
+  for (const r of records) byId.set(r.id, r);
+  let skippedOrphans = 0;
+  const kept: { dzId: string; rec: MemoryRecord }[] = [];
+  for (const dzId of sourceDzIds) {
+    const rec = byId.get(dzId);
+    if (rec === undefined) skippedOrphans += 1;
+    else kept.push({ dzId, rec });
+  }
+  if (kept.length === 0) return { imported: 0, skippedOrphans, engine: engine.kind, source };
+
+  // 4. VECTOR per kept dzId: injected verbatim vector, else RE-EMBED the local text (D7).
+  let embed = opts.embed;
+  if (embed === undefined && kept.some((k) => !injected.has(k.dzId))) {
+    const emb = await resolveAgentdbEmbedder(projectRoot);
+    if ('error' in emb) return { imported: 0, skippedOrphans, engine: engine.kind, source, error: emb.error };
+    embed = (t) => emb.embed(t);
+  }
+  const rows: ImportVectorRow[] = [];
+  for (const { dzId, rec } of kept) {
+    const taskType = dzId.startsWith('dream:') ? 'dz-learning' : 'dz-teach';
+    let vector = injected.get(dzId);
+    if (vector === undefined) {
+      const v = await boundedEmbed(embed!, `${taskType}: ${rec.text}`, timeoutMs);
+      if (!(v instanceof Float32Array)) {
+        return { imported: 0, skippedOrphans, engine: engine.kind, source, error: `embed failed: ${(v as { error: string }).error}` };
+      }
+      vector = v;
+    }
+    rows.push({ dzId, vector, text: rec.text, taskType, score: rec.score, metadata: { dzId } });
+  }
+
+  // 5. UPSERT-BY-dzId (re-import of the same dzIds REPLACEs in place — 0 new rows, nothing deleted).
+  const up = await engine.importVectors(rows);
+  if (up.error !== undefined) return { imported: up.imported, skippedOrphans, engine: engine.kind, source, error: up.error };
+  return { imported: up.imported, skippedOrphans, engine: engine.kind, source };
+}
+
 /* ------------------------------------------------------------------ */
 /*  Adapter A (default): AgentdbVectorEngine                           */
 /* ------------------------------------------------------------------ */
@@ -769,6 +1237,19 @@ function agentdbVectorEngine(projectRoot: string): VectorEngine {
     async listIds() {
       return listAgentdbDzIds(projectRoot);
     },
+    async importVectors(rows) {
+      return importVectorsToAgentdb(
+        projectRoot,
+        rows.map((r) => ({
+          dzId: r.dzId,
+          vector: r.vector,
+          text: r.text,
+          taskType: r.taskType,
+          score: r.score,
+          ...(r.metadata !== undefined ? { metadata: r.metadata } : {}),
+        })),
+      );
+    },
   };
 }
 
@@ -928,6 +1409,26 @@ function rvfVectorEngine(projectRoot: string): VectorEngine {
       // Sidecar-only read — no SDK load needed for observability/dedup.
       return { ids: [...new Set(Object.values(readRvfIdmap(projectRoot).slots))] };
     },
+    async importVectors(rows) {
+      const loaded = await loadRvfModule(projectRoot);
+      if (!loaded.ok) return { imported: 0, error: loaded.error };
+      const store = await openRvfStore(loaded.mod, rvfBase(projectRoot), 384);
+      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
+          idmap.slots[r.dzId] = r.dzId;
+          imported += 1;
+        }
+        await store.close?.();
+        writeRvfSidecars(projectRoot, idmap);
+        return { imported };
+      } catch (err) {
+        return { imported: 0, error: `rvf import failed: ${err instanceof Error ? err.message : String(err)}` };
+      }
+    },
     async exportCheckpoint(dest) {
       try {
         const base = rvfBase(projectRoot);