@dzhechkov/harness-core 0.3.78 → 0.3.80

package/dist/vector-tier.d.ts

@@ -68,6 +68,15 @@ export interface MirrorReceipt {
     readonly engine?: VectorEngineKind | undefined;
     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;
@@ -87,6 +96,15 @@ export interface VectorEngine {
     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. */
 export interface ResolvedVectorEngine {
@@ -125,6 +143,85 @@ export interface VectorTierStatus {
 }
 /** Wall-time bound applied to EVERY engine call, read and write legs alike (ADR R1 + NC1). */
 export declare const DEFAULT_VECTOR_TIMEOUT_MS = 10000;
+/** Default cosine cutoff for near-duplicate clustering (`--threshold` / config overrides). */
+export declare const DEFAULT_HARMONIZE_THRESHOLD = 0.92;
+/** 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;
+}
 /**
  * Bound `promise` to `ms` wall-clock milliseconds. On timeout, resolve with `onTimeout()`
  * instead — the underlying operation keeps running detached (its eventual write is later
@@ -150,6 +247,11 @@ export declare function dreamVectorEntry(d: DreamPattern): VectorEntry | undefin
 export declare function memoryRecordVectorEntry(r: MemoryRecord): VectorEntry | undefined;
 /** Read `memory.vector.engine` from `.dz/config.json`. Absent/corrupt ⇒ `auto` (never throws). */
 export declare 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 declare function readHarmonizeThreshold(projectRoot: string): number;
 /**
  * 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
@@ -217,6 +319,43 @@ export declare function recallHybrid(projectRoot: string, query: string, opts?:
 }): Promise<HybridRecall>;
 /** Field observability: engine availability + mirrored-vs-lexical counts + queue size. */
 export declare function vectorTierStatus(projectRoot: string, opts?: VectorServiceOptions): Promise<VectorTierStatus>;
+/**
+ * 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 declare function selectClusterKeeper(members: readonly HarmonizeItem[]): number;
+/**
+ * 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 declare function harmonizeVectorStore(projectRoot: string, opts?: HarmonizeOptions): Promise<HarmonizeReport>;
+/**
+ * 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 declare function importRvfCheckpoint(projectRoot: string, source: string, opts?: ImportOptions): Promise<ImportReport>;
 interface RvfStoreHandle {
     ingest: (id: string, vec: Float32Array) => Promise<unknown> | unknown;
     query: (vec: Float32Array, k: number) => Promise<unknown> | unknown;

package/dist/vector-tier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vector-tier.d.ts","sourceRoot":"","sources":["../src/vector-tier.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vector-tier.d.ts","sourceRoot":"","sources":["../src/vector-tier.ts"],"names":[],"mappings":"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"}

package/dist/vector-tier.js

@@ -32,14 +32,19 @@
  * @packageDocumentation
  */
 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';
 import { isNoiseInsight } from '@dzhechkov/memory';
-import { recallPatterns, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, loadStoreRecords, } from './patterns.js';
-import { indexPatternsToAgentdb, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder } from './agentdb-index.js';
+import { recallPatterns, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, loadStoreRecords, removePatternsByIds, snapshotStore, } from './patterns.js';
+import { indexPatternsToAgentdb, searchAgentdbPatterns, listAgentdbDzIds, resolveAgentdbEmbedder, cosineSimilarity, importVectorsToAgentdb, } from './agentdb-index.js';
 /** 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;
 /* ------------------------------------------------------------------ */
 /*  Timeout wrapper (both legs — NC1/QR-1)                             */
 /* ------------------------------------------------------------------ */
@@ -150,6 +155,20 @@ export function readVectorEngineMode(projectRoot) {
         return 'auto';
     }
 }
+/**
+ * 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) {
+    try {
+        const cfg = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8'));
+        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
@@ -546,6 +565,351 @@ export async function vectorTierStatus(projectRoot, opts = {}) {
     };
 }
 /* ------------------------------------------------------------------ */
+/*  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, timeoutMs) {
+    return withVectorTimeout(safeEngineCall(() => 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) {
+    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, b) {
+    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, edges) {
+    const parent = Array.from({ length: n }, (_, i) => i);
+    const find = (x) => {
+        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();
+    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, indices, cosToKeeper) {
+    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, vecs, threshold) {
+    const n = items.length;
+    const edges = [];
+    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 = [];
+    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) {
+    const byText = new Map();
+    items.forEach((it, i) => {
+        const g = byText.get(it.text);
+        if (g === undefined)
+            byText.set(it.text, [i]);
+        else
+            g.push(i);
+    });
+    const clusters = [];
+    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, info) {
+    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, opts = {}) {
+    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;
+    try {
+        records = loadStoreRecords(projectRoot);
+    }
+    catch {
+        records = [];
+    }
+    const items = 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;
+    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;
+    if (items.length >= 2 && !fellBackToExact && embed !== undefined) {
+        const vecs = [];
+        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();
+    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 = {
+        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, source, opts = {}) {
+    const fail = (error, engine = 'none') => ({ 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();
+    let sourceDzIds;
+    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;
+        try {
+            const parsed = JSON.parse(readFileSync(idmapPath, 'utf-8'));
+            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'));
+                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;
+    try {
+        records = loadStoreRecords(projectRoot);
+    }
+    catch {
+        records = [];
+    }
+    const byId = new Map();
+    for (const r of records)
+        byId.set(r.id, r);
+    let skippedOrphans = 0;
+    const kept = [];
+    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 = [];
+    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.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                           */
 /* ------------------------------------------------------------------ */
 /**
@@ -579,6 +943,16 @@ function agentdbVectorEngine(projectRoot) {
         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 } : {}),
+            })));
+        },
     };
 }
 function rvfBase(projectRoot) {
@@ -722,6 +1096,29 @@ function rvfVectorEngine(projectRoot) {
             // 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);