@dzhechkov/harness-core 0.3.76 → 0.3.80

package/dist/vector-tier.js

@@ -0,0 +1,1154 @@
+/**
+ * Vector Tier — the SEMANTIC half of the dz self-learning pattern store
+ * (`features/dz-rvf-vector-bridge`, ADR-001 "Option A extended").
+ *
+ * One PORT ({@link VectorEngine}) with two adapters behind it:
+ *
+ * - **AgentdbVectorEngine** (default) — reuses the `.dz/agentdb.db` ReasoningBank store the
+ *   consolidate Option-C mirror already writes (`agentdb-index.ts`), so semantic recall reads
+ *   the vectors that exist today. Zero new dependencies: `agentdb`/`better-sqlite3` are
+ *   dynamically resolved from the PROJECT, never imported at module top level.
+ * - **RvfVectorEngine** (opt-in, `memory.vector.engine = "rvf"`) — the portable single-file
+ *   VECTOR form (`.dz/memory/patterns.rvf` + `.idmap.json`/`.manifest.json` sidecars) via a
+ *   lazily imported `@ruvector/rvf`. Never a `dependencies` entry (at most a documentation-only
+ *   `peerDependenciesMeta`).
+ *
+ * HONEST-ERROR CONTRACT (load-bearing, Invariant I-1): every function in this module returns an
+ * honest `{ …, error?: string }` receipt and NEVER throws or hangs — engine absence, a failed
+ * embed, a locked DB, or a timeout all degrade to today's exact lexical behavior. The lexical
+ * store (`patterns.sqlite`/`patterns.json`) is the SOURCE OF TRUTH; the vector tier is a
+ * best-effort MIRROR that can be rebuilt from it at any time (`dz consolidate` backfill), and a
+ * vector hit whose lexical twin is gone is DROPPED, never resurrected (Invariant V-1).
+ *
+ * Constraint 7 (QR-10, field-diagnosis discipline): when lexical and vector counts diverge,
+ * **rule out local DB corruption before blaming the mirror** — check `dz doctor`'s store health
+ * first; the mirror's own divergence line (`dz vector status`) reports BOTH counts plus the
+ * `dz consolidate` backfill hint, and is informational, never an error.
+ *
+ * Both engine calls (read `search` AND write `upsert`/`listIds`) are wall-time bounded
+ * ({@link DEFAULT_VECTOR_TIMEOUT_MS}); a write-side timeout (e.g. a first-run embedding-model
+ * download) lands the batch in `.dz/mirror-pending.json` and never blocks `dz teach` (NC1).
+ *
+ * @packageDocumentation
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, renameSync, appendFileSync, copyFileSync } from 'node:fs';
+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, 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)                             */
+/* ------------------------------------------------------------------ */
+/**
+ * Bound `promise` to `ms` wall-clock milliseconds. On timeout, resolve with `onTimeout()`
+ * instead — the underlying operation keeps running detached (its eventual write is later
+ * deduplicated by dzId), but the CALLER's latency is bounded. A rejection also resolves via
+ * `onTimeout()` (honest-error contract: this wrapper never throws). The timer is cleared /
+ * unref'd so a fast path never keeps the process alive.
+ */
+export async function withVectorTimeout(promise, ms, onTimeout) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise.catch(() => onTimeout()),
+            new Promise((resolvePromise) => {
+                timer = setTimeout(() => resolvePromise(onTimeout()), ms);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Invoke an engine call so that BOTH a synchronous throw and an async rejection surface as an
+ * honest `onError(message)` value (never as the timeout fallback — a throw and a timeout are
+ * different diagnoses in the field). Pairs with {@link withVectorTimeout} at every call site.
+ */
+function safeEngineCall(fn, onError) {
+    const msg = (err) => (err instanceof Error ? err.message : String(err));
+    try {
+        return fn().then((v) => v, (err) => onError(msg(err)));
+    }
+    catch (err) {
+        return Promise.resolve(onError(msg(err)));
+    }
+}
+/* ------------------------------------------------------------------ */
+/*  Noise gate + ACL mappers (I-6, V-3)                                */
+/* ------------------------------------------------------------------ */
+const TOOL_TELEMETRY_RE = /^Tool \S+ invoked during session$/;
+/** Text that must never be embedded: bare-approval echoes + tool telemetry (V-3 / ADR-002). */
+export function isVectorNoise(text) {
+    return isNoiseInsight(text) || TOOL_TELEMETRY_RE.test(text);
+}
+/**
+ * ACL: taught {@link PatternRecord} → {@link VectorEntry}. Returns `undefined` for noise (the
+ * ingest gate — I-6). Score is the record's REAL reward, never a fabricated 1.0.
+ */
+export function patternVectorEntry(p, source = 'dz-teach') {
+    if (isVectorNoise(p.pattern))
+        return undefined;
+    const dzId = patternRecordId(p);
+    return {
+        dzId,
+        text: p.pattern,
+        score: p.reward,
+        taskType: 'dz-teach',
+        tags: ['dz-teach', p.type],
+        metadata: { dzId, source, ts: p.ts, domain: p.domain },
+    };
+}
+/**
+ * ACL: harvested {@link DreamPattern} → {@link VectorEntry}. Byte-compatible with the
+ * pre-feature consolidate mirror rows (same task_type `dz-learning`, same tags, `dreamId`
+ * preserved in metadata — NFR-7); `dzId` is additive.
+ */
+export function dreamVectorEntry(d) {
+    if (isVectorNoise(d.insight))
+        return undefined;
+    const dzId = dreamRecordId(d);
+    return {
+        dzId,
+        text: d.insight,
+        score: d.score,
+        taskType: 'dz-learning',
+        tags: ['dz-consolidate', d.outcome],
+        metadata: { source: 'dz-consolidate', skillId: d.skillId, sessionFile: d.sessionFile, ts: d.timestamp, dreamId: dzId, dzId },
+    };
+}
+/** ACL: stored {@link MemoryRecord} → {@link VectorEntry} (the consolidate-backfill mapper). */
+export function memoryRecordVectorEntry(r) {
+    if (isVectorNoise(r.text))
+        return undefined;
+    return {
+        dzId: r.id,
+        text: r.text,
+        score: r.score,
+        taskType: r.id.startsWith('dream:') ? 'dz-learning' : 'dz-teach',
+        tags: ['dz-backfill', r.outcome],
+        metadata: { dzId: r.id, source: r.metadata?.['source'] ?? 'dz-backfill', ts: r.timestamp, skillId: r.skillId },
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  Config + engine resolution cascade (05 §2.1)                       */
+/* ------------------------------------------------------------------ */
+/** Read `memory.vector.engine` from `.dz/config.json`. Absent/corrupt ⇒ `auto` (never throws). */
+export function readVectorEngineMode(projectRoot) {
+    try {
+        const cfg = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8'));
+        const mode = cfg.memory?.vector?.engine;
+        return mode === 'off' || mode === 'agentdb' || mode === 'rvf' || mode === 'auto' ? mode : 'auto';
+    }
+    catch {
+        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
+ * uses — D3) or explicitly configured a vector engine. A fresh, unconfigured project returns
+ * `false`, so its `dz teach` output stays byte-identical to the pre-feature baseline (AC-1).
+ */
+export function vectorMirrorEnabled(projectRoot) {
+    try {
+        const cfg = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8'));
+        if (cfg.memory?.backend === 'agentdb')
+            return true;
+        const engine = cfg.memory?.vector?.engine;
+        return engine === 'agentdb' || engine === 'rvf';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Engine selection cascade: config mode → `require.resolve` probe (NO module load — a
+ * lexical-only project pays zero engine cost, NFR-5) → adapter or an honest reason.
+ * Never throws. `auto` prefers agentdb (it reads the vectors consolidate already wrote),
+ * falling through to rvf.
+ */
+/**
+ * Is `pkgName` installed for this PROJECT? A pure filesystem probe: walk `node_modules` up the
+ * directory tree from `projectRoot` (the npm resolution chain) — deliberately NOT
+ * `require.resolve`, which also consults process-global paths (`NODE_PATH`/global folders) and
+ * would make a lexical-only project's engine availability depend on the HOST process instead
+ * of the project (the I-1 determinism leak). No module is loaded (NFR-5).
+ */
+function isPackageInstalled(projectRoot, pkgName) {
+    let dir = projectRoot;
+    for (;;) {
+        if (existsSync(join(dir, 'node_modules', pkgName, 'package.json')))
+            return true;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+export function resolveVectorEngine(projectRoot) {
+    const mode = readVectorEngineMode(projectRoot);
+    if (mode === 'off')
+        return { reason: 'vector tier disabled (memory.vector.engine = "off")' };
+    const canResolve = (id) => isPackageInstalled(projectRoot, id);
+    if (mode === 'agentdb' || mode === 'auto') {
+        if (canResolve('agentdb') && canResolve('better-sqlite3'))
+            return { engine: agentdbVectorEngine(projectRoot) };
+        if (mode === 'agentdb') {
+            return { reason: 'agentdb/better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
+        }
+    }
+    if (mode === 'rvf' || mode === 'auto') {
+        if (canResolve('@ruvector/rvf'))
+            return { engine: rvfVectorEngine(projectRoot) };
+        if (mode === 'rvf') {
+            return { reason: '@ruvector/rvf not installed in project (npm i @ruvector/rvf) — vector tier inactive' };
+        }
+    }
+    return { reason: 'no vector engine available: agentdb/better-sqlite3 not installed in project (run: dz setup --memory agentdb)' };
+}
+function pendingPath(projectRoot) {
+    return join(projectRoot, '.dz', 'mirror-pending.json');
+}
+function toPending(e) {
+    return { ...e, insight: e.text };
+}
+/** Legacy queue rows (pre-port `DreamPattern[]`) are converted on read — nothing is lost. */
+function readVectorPending(projectRoot) {
+    try {
+        const arr = JSON.parse(readFileSync(pendingPath(projectRoot), 'utf-8'));
+        if (!Array.isArray(arr))
+            return [];
+        const out = [];
+        for (const item of arr) {
+            if (typeof item !== 'object' || item === null)
+                continue;
+            const rec = item;
+            if (typeof rec['dzId'] === 'string' && typeof rec['text'] === 'string') {
+                out.push(toPending(rec));
+            }
+            else if (typeof rec['insight'] === 'string' && typeof rec['timestamp'] === 'string') {
+                const entry = dreamVectorEntry(rec);
+                if (entry !== undefined)
+                    out.push(toPending(entry));
+            }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function writeVectorPending(projectRoot, entries) {
+    try {
+        if (entries.length === 0) {
+            if (existsSync(pendingPath(projectRoot)))
+                rmSync(pendingPath(projectRoot));
+        }
+        else {
+            const path = pendingPath(projectRoot);
+            mkdirSync(dirname(path), { recursive: true });
+            // Atomic write: a concurrent teach/consolidate must never observe a torn file. Write to a
+            // temp sibling then rename() (atomic on POSIX). Recovery guarantee: even if a racing writer
+            // clobbers the queue, backfillVectorMirror re-derives the missing set from the lexical store,
+            // so a dropped entry is recovered on the next consolidate — no permanent loss.
+            const tmp = `${path}.tmp`;
+            writeFileSync(tmp, JSON.stringify(entries, null, 2));
+            renameSync(tmp, path);
+        }
+    }
+    catch { /* best-effort */ }
+}
+/** Honest failure note next to the session telemetry (the detached SessionEnd path is silent). */
+function logMirrorNote(projectRoot, error, pending) {
+    try {
+        appendFileSync(join(projectRoot, '.dz', 'sessions.jsonl'), JSON.stringify({ event: 'mirror', ts: new Date().toISOString(), error, pending }) + '\n');
+    }
+    catch { /* best-effort */ }
+}
+function pickEngine(projectRoot, opts) {
+    if (opts.engine === null)
+        return { reason: 'vector engine disabled (injected)' };
+    if (opts.engine !== undefined)
+        return { engine: opts.engine };
+    return resolveVectorEngine(projectRoot);
+}
+/**
+ * Mirror prepared {@link VectorEntry}s into the vector store — **the single write seam** that
+ * teach, `teach --from-json`, consolidate, and the backfill all route through (QR-6). The
+ * lexical write is ALWAYS already durable before this runs (I-3). Semantics:
+ *
+ * 1. noise-gate the entries (I-6), merge with the pending queue (dedup by dzId),
+ * 2. nothing to do ⇒ `{mirrored:0}` with NO error and no queue file,
+ * 3. engine absent ⇒ park the batch in the queue + honest reason (heals on the next consolidate),
+ * 4. dedup against `engine.listIds()` (I-5 idempotency — a re-mirror adds 0 rows),
+ * 5. time-bounded `engine.upsert` (NC1); failure/timeout ⇒ queue + `sessions.jsonl` note.
+ *
+ * NEVER throws; the caller's exit code is unaffected by any outcome here (I-1).
+ */
+export async function mirrorEntriesToVector(projectRoot, entries, opts = {}) {
+    try {
+        let skipped = 0;
+        const gated = [];
+        for (const e of entries) {
+            if (isVectorNoise(e.text))
+                skipped += 1;
+            else
+                gated.push(e);
+        }
+        const byId = new Map();
+        for (const e of [...readVectorPending(projectRoot), ...gated.map(toPending)]) {
+            if (!byId.has(e.dzId))
+                byId.set(e.dzId, e);
+        }
+        const batch = [...byId.values()];
+        if (batch.length === 0)
+            return { mirrored: 0, skipped, queued: 0 };
+        const resolved = pickEngine(projectRoot, opts);
+        if (resolved.engine === undefined) {
+            writeVectorPending(projectRoot, batch);
+            const error = resolved.reason ?? 'no vector engine available';
+            logMirrorNote(projectRoot, error, batch.length);
+            return { mirrored: 0, skipped, queued: batch.length, error };
+        }
+        const engine = resolved.engine;
+        const timeoutMs = opts.timeoutMs ?? DEFAULT_VECTOR_TIMEOUT_MS;
+        // I-5 idempotency: skip what the store already holds (best-effort, time-bounded).
+        let toSend = batch;
+        const listed = await withVectorTimeout(safeEngineCall(() => engine.listIds(), (m) => ({ ids: [], error: `vector listIds failed: ${m}` })), timeoutMs, () => ({ ids: [], error: 'vector listIds timed out' }));
+        if (listed.error === undefined) {
+            const have = new Set(listed.ids);
+            const before = toSend.length;
+            toSend = toSend.filter((e) => !have.has(e.dzId));
+            skipped += before - toSend.length;
+        }
+        if (toSend.length === 0) {
+            writeVectorPending(projectRoot, []);
+            return { mirrored: 0, skipped, queued: 0, engine: engine.kind };
+        }
+        const up = await withVectorTimeout(safeEngineCall(() => engine.upsert(toSend.map(({ insight: _insight, ...entry }) => entry)), (m) => ({ indexed: 0, error: `vector mirror failed: ${m}` })), timeoutMs, () => ({ indexed: 0, error: `vector mirror timed out after ${timeoutMs}ms (batch queued for the next consolidate)` }));
+        if (up.error !== undefined) {
+            writeVectorPending(projectRoot, toSend);
+            logMirrorNote(projectRoot, up.error, toSend.length);
+            return { mirrored: up.indexed, skipped, queued: toSend.length, engine: engine.kind, error: up.error };
+        }
+        writeVectorPending(projectRoot, []);
+        return { mirrored: up.indexed, skipped, queued: 0, engine: engine.kind };
+    }
+    catch (err) {
+        // Belt-and-braces: the mirror must NEVER take the caller down (I-1/I-3).
+        return { mirrored: 0, skipped: 0, queued: 0, error: `mirror failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/** Convenience seam for taught patterns: ACL-map + delegate to {@link mirrorEntriesToVector}. */
+export async function mirrorPatternsToVector(projectRoot, patterns, source = 'dz-teach', opts = {}) {
+    const entries = [];
+    let gatedOut = 0;
+    for (const p of patterns) {
+        const e = patternVectorEntry(p, source);
+        if (e !== undefined)
+            entries.push(e);
+        else
+            gatedOut += 1; // noise never maps (I-6) — reported honestly as skipped
+    }
+    const receipt = await mirrorEntriesToVector(projectRoot, entries, opts);
+    return gatedOut === 0 ? receipt : { ...receipt, skipped: receipt.skipped + gatedOut };
+}
+/**
+ * Eventual consistency (FR-2): diff `lexical dzIds ∖ engine.listIds()` and mirror the missing
+ * set (bounded batch) + drain the pending queue. Run by `dz consolidate` after the watermark
+ * write, so a teach-time mirror failure heals on the next consolidate (AC-3). Engine absent ⇒
+ * silent no-op (the absent tier is a state, not an error).
+ */
+export async function backfillVectorMirror(projectRoot, opts = {}) {
+    try {
+        const resolved = pickEngine(projectRoot, opts);
+        if (resolved.engine === undefined) {
+            return { mirrored: 0, skipped: 0, queued: readVectorPending(projectRoot).length };
+        }
+        const engine = resolved.engine;
+        const timeoutMs = opts.timeoutMs ?? DEFAULT_VECTOR_TIMEOUT_MS;
+        const listed = await withVectorTimeout(safeEngineCall(() => engine.listIds(), (m) => ({ ids: [], error: `vector listIds failed: ${m}` })), timeoutMs, () => ({ ids: [], error: 'vector listIds timed out' }));
+        if (listed.error !== undefined) {
+            return { mirrored: 0, skipped: 0, queued: readVectorPending(projectRoot).length, engine: engine.kind, error: listed.error };
+        }
+        const have = new Set(listed.ids);
+        const limit = opts.batchLimit ?? 200;
+        const missing = [];
+        for (const r of loadStoreRecords(projectRoot)) {
+            if (have.has(r.id))
+                continue;
+            const e = memoryRecordVectorEntry(r);
+            if (e === undefined)
+                continue;
+            missing.push(e);
+            if (missing.length >= limit)
+                break;
+        }
+        // The seam drains the pending queue too (it merges + dedups internally).
+        return mirrorEntriesToVector(projectRoot, missing, { engine, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    }
+    catch (err) {
+        return { mirrored: 0, skipped: 0, queued: 0, error: `backfill failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+const RRF_K = 60;
+/**
+ * Reciprocal Rank Fusion merge: `score(p) = Σ 1/(60 + rank)` over the lists containing `p`
+ * (semantic ranks weighted by `semanticWeight`). Dedup by id; `backend: 'both'` when a pattern
+ * appears in both lists. DETERMINISTIC (AC-6): ties break on id, so fixed inputs always yield
+ * the same ordering. Pure — no I/O.
+ */
+export function mergeHybridHits(lexical, semantic, opts) {
+    const weight = opts.semanticWeight ?? 1;
+    const acc = new Map();
+    lexical.forEach((h, rank) => {
+        const cur = acc.get(h.id) ?? { pattern: h.pattern, sem: false, score: 0 };
+        cur.lex = h.backend;
+        cur.score += 1 / (RRF_K + rank + 1);
+        acc.set(h.id, cur);
+    });
+    semantic.forEach((h, rank) => {
+        const cur = acc.get(h.id) ?? { pattern: h.pattern, sem: false, score: 0 };
+        cur.sem = true;
+        cur.score += weight / (RRF_K + rank + 1);
+        acc.set(h.id, cur);
+    });
+    return [...acc.entries()]
+        .sort((a, b) => b[1].score - a[1].score || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+        .slice(0, opts.limit)
+        .map(([, v]) => ({
+        pattern: v.pattern,
+        backend: v.lex !== undefined && v.sem ? 'both' : v.lex ?? 'vector',
+        score: v.score,
+    }));
+}
+/**
+ * Hybrid recall (FR-3): lexical `recallPatterns` FIRST (always, sync, UNCHANGED — AC-5), then a
+ * time-bounded semantic leg merged via RRF. Degradation contract (I-1): with no engine — or on
+ * any engine error/timeout — the returned hits are CONTENT-IDENTICAL to plain `recallPatterns`
+ * output, with the honest `vectorReason`/`vectorError` alongside. A vector hit whose dzId no
+ * longer resolves in the lexical store is DROPPED (V-1 — pruned patterns never resurrect, QR-4).
+ */
+export async function recallHybrid(projectRoot, query, opts = {}) {
+    // Config-surface note (QE P3, benign by design): recall resolves the engine directly, while teach
+    // only mirrors when the memory backend is agentdb (or an engine is explicit). In the window where
+    // the agentdb deps are INSTALLED but `memory.backend` hasn't been switched, the semantic leg reads a
+    // store teach never populated → empty/foreign hits. That degrades honestly (orphan dzIds are dropped
+    // against the lexical store, V-1) and lexical results are always returned, so it never misleads — it
+    // only spends a bounded, cached read. Not gated on purpose: a read-only recall must not depend on the
+    // write-side backend flag.
+    const limit = opts.limit ?? 10;
+    const mode = opts.mode ?? 'hybrid';
+    const lexical = recallPatterns(projectRoot, query, limit);
+    const lexicalBackend = lexical[0]?.backend === 'sqlite' ? 'sqlite' : 'json';
+    const lexicalOnly = (extra) => ({
+        hits: lexical.map((h, rank) => ({ pattern: h.pattern, backend: h.backend, score: 1 / (RRF_K + rank + 1) })),
+        lexicalBackend,
+        vectorEngine: 'none',
+        ...extra,
+    });
+    if (mode === 'lexical')
+        return lexicalOnly({});
+    let resolved;
+    try {
+        resolved = pickEngine(projectRoot, opts);
+    }
+    catch (err) {
+        return lexicalOnly({ vectorReason: err instanceof Error ? err.message : String(err) });
+    }
+    if (resolved.engine === undefined) {
+        return lexicalOnly(resolved.reason !== undefined ? { vectorReason: resolved.reason } : {});
+    }
+    const engine = resolved.engine;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_VECTOR_TIMEOUT_MS;
+    const sr = await withVectorTimeout(safeEngineCall(() => engine.search(query, limit * 2), (m) => ({ hits: [], error: `vector search failed: ${m}` })), timeoutMs, () => ({ hits: [], error: `vector search timed out after ${timeoutMs}ms` }));
+    if (sr.error !== undefined) {
+        return { ...lexicalOnly({}), vectorEngine: engine.kind, vectorError: sr.error };
+    }
+    // Resolve dzId → the FULL lexical record (source of truth). Orphans are dropped (V-1/QR-4).
+    let records;
+    try {
+        records = loadStoreRecords(projectRoot);
+    }
+    catch {
+        records = [];
+    }
+    const idToPattern = new Map();
+    const identityToId = new Map();
+    for (const r of records) {
+        const p = recordToPattern(r);
+        idToPattern.set(r.id, p);
+        identityToId.set(patternIdentityOf(p), r.id);
+    }
+    const semantic = [];
+    const seen = new Set();
+    for (const h of sr.hits) {
+        if (seen.has(h.dzId))
+            continue;
+        const p = idToPattern.get(h.dzId);
+        if (p === undefined)
+            continue; // vector-only orphan — the store pruned/expired it; NEVER resurrect
+        seen.add(h.dzId);
+        semantic.push({ id: h.dzId, pattern: p, backend: 'vector' });
+    }
+    const lex = lexical.map((h) => ({
+        id: identityToId.get(patternIdentityOf(h.pattern)) ?? patternRecordId(h.pattern),
+        pattern: h.pattern,
+        backend: h.backend,
+    }));
+    const hits = mergeHybridHits(lex, semantic, { limit, semanticWeight: mode === 'semantic' ? 2 : 1 });
+    return { hits, lexicalBackend, vectorEngine: engine.kind };
+}
+/* ------------------------------------------------------------------ */
+/*  Status (dz vector status / dz doctor divergence line)              */
+/* ------------------------------------------------------------------ */
+/** Field observability: engine availability + mirrored-vs-lexical counts + queue size. */
+export async function vectorTierStatus(projectRoot, opts = {}) {
+    const mode = readVectorEngineMode(projectRoot);
+    let records;
+    try {
+        records = loadStoreRecords(projectRoot);
+    }
+    catch {
+        records = [];
+    }
+    const lexicalMirrorable = records.filter((r) => !isVectorNoise(r.text)).length;
+    const pending = readVectorPending(projectRoot).length;
+    const resolved = pickEngine(projectRoot, opts);
+    if (resolved.engine === undefined) {
+        return {
+            mode,
+            available: false,
+            ...(resolved.reason !== undefined ? { reason: resolved.reason } : {}),
+            lexicalTotal: records.length,
+            lexicalMirrorable,
+            pending,
+        };
+    }
+    const engine = resolved.engine;
+    const listed = await withVectorTimeout(safeEngineCall(() => engine.listIds(), (m) => ({ ids: [], error: `vector listIds failed: ${m}` })), opts.timeoutMs ?? DEFAULT_VECTOR_TIMEOUT_MS, () => ({ ids: [], error: 'vector listIds timed out' }));
+    return {
+        mode,
+        kind: engine.kind,
+        available: true,
+        ...(listed.error !== undefined ? { reason: listed.error } : {}),
+        lexicalTotal: records.length,
+        lexicalMirrorable,
+        mirrored: listed.error === undefined ? listed.ids.length : undefined,
+        pending,
+    };
+}
+/* ------------------------------------------------------------------ */
+/*  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                           */
+/* ------------------------------------------------------------------ */
+/**
+ * Option A: the `.dz/agentdb.db` ReasoningBank store. `upsert` delegates to the very same
+ * {@link indexPatternsToAgentdb} rows the consolidate Option-C mirror writes today (schema
+ * unchanged — the `agentdb-memory` MCP skill keeps reading them, NFR-7); `search`/`listIds`
+ * are the new READONLY halves in `agentdb-index.ts`.
+ */
+function agentdbVectorEngine(projectRoot) {
+    return {
+        kind: 'agentdb',
+        async upsert(entries) {
+            const r = await indexPatternsToAgentdb(projectRoot, entries.map((e) => ({
+                taskType: e.taskType,
+                text: e.text,
+                score: e.score,
+                ...(e.tags !== undefined ? { tags: e.tags } : {}),
+                ...(e.metadata !== undefined ? { metadata: e.metadata } : {}),
+            })));
+            return { indexed: r.indexed, ...(r.error !== undefined ? { error: r.error } : {}) };
+        },
+        async search(query, limit) {
+            const r = await searchAgentdbPatterns(projectRoot, query, { limit });
+            const hits = [];
+            for (const h of r.hits) {
+                if (h.dzId !== undefined)
+                    hits.push({ dzId: h.dzId, similarity: h.similarity, text: h.text });
+            }
+            return { hits, ...(r.error !== undefined ? { error: r.error } : {}) };
+        },
+        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) {
+    return join(projectRoot, '.dz', 'memory', 'patterns.rvf');
+}
+function readRvfIdmap(projectRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(`${rvfBase(projectRoot)}.idmap.json`, 'utf-8'));
+        return typeof parsed === 'object' && parsed !== null && typeof parsed.slots === 'object' ? parsed : { version: 1, slots: {} };
+    }
+    catch {
+        return { version: 1, slots: {} };
+    }
+}
+function writeRvfSidecars(projectRoot, idmap) {
+    const base = rvfBase(projectRoot);
+    mkdirSync(dirname(base), { recursive: true });
+    writeFileSync(`${base}.idmap.json`, JSON.stringify(idmap, null, 2));
+    writeFileSync(`${base}.manifest.json`, JSON.stringify({ model: 'Xenova/all-MiniLM-L6-v2', dim: 384, engine: '@ruvector/rvf', version: 1 }, null, 2));
+}
+/**
+ * Open a `@ruvector/rvf` store, pinned to the REAL published SDK surface (grounded in
+ * ruvector/npm/packages/rvf/src/index.ts + a live linux-x64 smoke against @ruvector/rvf@0.2.3):
+ * the canonical class is `RvfDatabase` with `create(path, { dimensions })` → `ingestBatch([{id,
+ * vector}])` → `query(vector, k)` returning `[{ id, distance }]` → `close()`. A few tolerant
+ * fallbacks (add/insert, search) keep older/alt shapes working; anything unrecognized returns an
+ * HONEST error (the D8 no-go evidence), never a throw. NOTE: RVF stores the vector under the `id`
+ * we pass (= the dzId), so no slot↔id mapping is needed — the query result's `id` IS the dzId.
+ */
+export async function openRvfStore(mod, path, dimensions) {
+    try {
+        const dflt = mod['default'];
+        const cls = (mod['RvfDatabase'] ?? dflt?.['RvfDatabase'] ?? mod['RvfStore'] ?? mod['Store'] ?? dflt?.['RvfStore'] ?? dflt ?? mod);
+        let db;
+        if (typeof cls.create === 'function')
+            db = (await cls.create(path, { dimensions, dimension: dimensions }));
+        else if (typeof cls.open === 'function')
+            db = (await cls.open(path, { dimensions, dimension: dimensions }));
+        else if (typeof cls === 'function')
+            db = new cls(path, { dimensions });
+        if (db === undefined)
+            return { error: 'unsupported @ruvector/rvf API (no RvfDatabase.create/open/constructor) — record a D8 no-go' };
+        const ingestBatch = (db['ingestBatch'] ?? db['ingest'] ?? db['add'] ?? db['insert']);
+        const query = (db['query'] ?? db['search']);
+        if (typeof ingestBatch !== 'function' || typeof query !== 'function') {
+            return { error: 'unsupported @ruvector/rvf store surface (no ingestBatch/ingest + query/search) — record a D8 no-go' };
+        }
+        const close = db['close'];
+        const exp = db['exportCheckpoint'] ?? db['export_checkpoint'] ?? db['checkpoint'];
+        return {
+            ingest: (id, vec) => ingestBatch.call(db, [{ id, vector: vec }]),
+            query: (vec, k) => query.call(db, vec, k),
+            close: typeof close === 'function' ? close.bind(db) : undefined,
+            exportCheckpoint: typeof exp === 'function' ? exp.bind(db) : undefined,
+        };
+    }
+    catch (err) {
+        return { error: `@ruvector/rvf store open failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+async function loadRvfModule(projectRoot) {
+    try {
+        const req = createRequire(join(projectRoot, 'package.json'));
+        const mod = (await import(pathToFileURL(req.resolve('@ruvector/rvf')).href));
+        return { ok: true, mod };
+    }
+    catch (err) {
+        return { ok: false, error: `@ruvector/rvf failed to load: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Option B: the portable single-file VECTOR form (`.rvf`, magic `0x52564653`) with
+ * `.idmap.json` (slot ↔ dzId) and `.manifest.json` (model/dim — Constraint 5 staleness
+ * detection) sidecars. Embeddings come from agentdb's `EmbeddingService` when resolvable —
+ * with NEITHER embedder the engine degrades gracefully with an honest reason (05 §3.6).
+ */
+function rvfVectorEngine(projectRoot) {
+    const noEmbedder = 'rvf engine present but no embedder — install agentdb (dz setup --memory agentdb)';
+    return {
+        kind: 'rvf',
+        async upsert(entries) {
+            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);
+            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}`);
+                    await store.ingest(e.dzId, vec); // RVF stores the vector UNDER id = dzId (no slot mapping)
+                    idmap.slots[e.dzId] = e.dzId; // sidecar keeps the dzId set for listIds/observability
+                    indexed += 1;
+                }
+                await store.close?.();
+                writeRvfSidecars(projectRoot, idmap);
+                return { indexed };
+            }
+            catch (err) {
+                return { indexed: 0, error: `rvf upsert failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+        },
+        async search(query, limit) {
+            const emb = await resolveAgentdbEmbedder(projectRoot);
+            if ('error' in emb)
+                return { hits: [], error: noEmbedder };
+            const loaded = await loadRvfModule(projectRoot);
+            if (!loaded.ok)
+                return { hits: [], error: loaded.error };
+            const store = await openRvfStore(loaded.mod, rvfBase(projectRoot), 384);
+            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 = [];
+                if (Array.isArray(raw)) {
+                    for (const item of raw) {
+                        const id = Array.isArray(item) ? item[0] : item['id'] ?? item['slot'] ?? item['label'];
+                        const distance = Array.isArray(item) ? item[1] : item['distance'] ?? item['score'] ?? item['similarity'];
+                        // RVF returns the id we ingested (= dzId); the sidecar is a safety join for alt shapes.
+                        const dzId = idmap.slots[String(id)] ?? (typeof id === 'string' ? id : undefined);
+                        // distance: lower = closer → negate so higher = better (RRF ranks by position regardless).
+                        if (dzId !== undefined)
+                            hits.push({ dzId, similarity: typeof distance === 'number' ? -distance : 0 });
+                    }
+                }
+                return { hits };
+            }
+            catch (err) {
+                return { hits: [], error: `rvf search failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+        },
+        async listIds() {
+            // 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);
+                if (!existsSync(base))
+                    return { error: `no ${base} yet — teach/consolidate with the rvf engine first` };
+                const loaded = await loadRvfModule(projectRoot);
+                let exported = false;
+                if (loaded.ok) {
+                    const store = await openRvfStore(loaded.mod, base, 384);
+                    if (!('error' in store) && store.exportCheckpoint !== undefined) {
+                        await store.exportCheckpoint(dest);
+                        await store.close?.();
+                        exported = true;
+                    }
+                    else if (!('error' in store)) {
+                        await store.close?.();
+                    }
+                }
+                if (!exported)
+                    copyFileSync(base, dest); // append-only format — a file copy IS a checkpoint
+                for (const sidecar of ['.idmap.json', '.manifest.json']) {
+                    if (existsSync(`${base}${sidecar}`))
+                        copyFileSync(`${base}${sidecar}`, `${dest}${sidecar}`);
+                }
+                return {};
+            }
+            catch (err) {
+                return { error: `rvf export failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+        },
+    };
+}
+//# sourceMappingURL=vector-tier.js.map