pi-mega-compact 0.8.21 → 0.8.23

package/dist/src/vectorStore.js

@@ -16,13 +16,8 @@ import { computeContentDigest } from "./dedup/digest.js";
 import { minhashSignature, SIGNATURE_VERSION, NUM_HASHES } from "./dedup/l1-minhash.js";
 import { lshBands } from "./dedup/l1-lsh.js";
 import { isNearDuplicate } from "./dedup/l1-verify.js";
-import { mmrRerank } from "./dedup/mmr.js";
-import { topK } from "./dedup/topk.js";
 import { openBloom, saveBloom } from "./store/bloom.js";
-import { listCheckpoints, nextCheckpointId, upsertCheckpoint, getCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, lshCandidateChunks, setDedupStatus, addTokensSaved, getDedupStats, bumpDedupStats, repoStats as repoStatsFromStore, dataInvariantStats, maxCheckpointTimestamp, } from "./store/sqlite.js";
-import { initVectorIndex, searchAsync as vectorIndexSearch, } from "./store/vectorIndex.js";
-import { rehydrateRaptorTree, isShadowMode } from "./dedup/raptor/index.js";
-import { stagedExpansion } from "./dedup/raptor/retrieval.js";
+import { listCheckpoints, nextCheckpointId, upsertCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, lshCandidateChunks, addTokensSaved, bumpDedupStats, } from "./store/sqlite.js";
 import { migrateJsonToSqlite } from "./store/migrate.js";
 /** Default L2 semantic-dedup enable flag (trigram embedder is local, zero-network). */
 export const L2_ENABLED = true;
@@ -33,6 +28,11 @@ export function computeRegionHash(regionText) {
     return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
 }
 export class VectorStore {
+    // These fields are `readonly` (set once in the constructor) but NOT private:
+    // the read/search/dedup helpers split into vector-read.ts, vector-search.ts,
+    // and vector-dedup.ts access them directly. Marking them private would force
+    // ugly `as unknown as` casts in those modules; keeping them package-public
+    // makes VectorStore a thin barrel whose helpers live in sibling files.
     embedder;
     stateDir;
     l2Threshold;
@@ -327,295 +327,8 @@ export class VectorStore {
         }
         return undefined;
     }
-    /**
-     * Semantic search within a session's checkpoints. Returns top-K by cosine
-     * similarity, diversified via MMR (QA #10) so a cluster of near-identical
-     * hits yields at most a few distinct-relevance results.
-     *
-     * Heap-based top-K (QA #4, O(N log k)) replaces the old full sort; MMR then
-     * reranks the candidate window for diversity.
-     */
-    search(sessionId, query, k = 3) {
-        const sid = normalizeSessionId(sessionId);
-        const checkpoints = listCheckpoints(sid, this.stateDir).filter((cp) => cp.dedupStatus !== "removed");
-        if (checkpoints.length === 0)
-            return [];
-        const qv = this.embedder.embed(query);
-        const scored = checkpoints.map((cp) => ({
-            checkpoint: cp,
-            score: cosineSimilarity(qv, cp.embedding),
-        }));
-        // Heap top-K over a widened window (2k) so MMR has diverse candidates.
-        const window = topK(scored.map((h) => ({ item: h, score: h.score })), Math.max(k * 2, k)).map((s) => s.item);
-        // MMR (QA #10) is part of the L2 semantic tier: skip it when L2 is disabled
-        // (Sprint 14 flag), returning the plain relevance-ranked window instead.
-        if (!this.cfg.L2_ENABLED)
-            return window.slice(0, k);
-        // Fix D: when RAPTOR is promoted, ALSO recall high-level tree summaries and
-        // merge them with the flat hits via MMR so RAPTOR + flat don't double-cover.
-        // RAPTOR returns fewer, broader hits (O(log n) high-level nodes) than the
-        // O(n) flat leaves, tightening the block at read time.
-        if (this.cfg.RAPTOR_ENABLED) {
-            const raptorHits = this.raptorSearchHits(sid, query, k);
-            if (raptorHits.length > 0) {
-                const merged = [...window];
-                for (const rh of raptorHits) {
-                    if (!merged.some((m) => m.checkpoint.checkpointId === rh.checkpoint.checkpointId)) {
-                        merged.push(rh);
-                    }
-                }
-                const mmrItems = merged.map((h) => ({
-                    item: h,
-                    vector: h.checkpoint.embedding,
-                    relevance: h.score,
-                }));
-                return mmrRerank(mmrItems, k, this.cfg.MMR_LAMBDA);
-            }
-        }
-        const mmrItems = window.map((h) => ({
-            item: h,
-            vector: h.checkpoint.embedding,
-            relevance: h.score,
-        }));
-        const ranked = mmrRerank(mmrItems, k, this.cfg.MMR_LAMBDA);
-        return ranked;
-    }
-    /**
-     * Slice 2: async cross-repo (or single-repo) recall via the PGlite/HNSW index.
-     *
-     * This is the ONLY async recall surface and is a BONUS path — the synchronous
-     * `search()` above remains the default. `opts.repoId` scopes to one repo; omit
-     * it for cross-repo nearest-neighbor recall (the headline capability the sync
-     * per-session scan cannot provide).
-     *
-     * Best-effort: if the index is disabled/empty/failing, we fall back to the
-     * synchronous per-session `search()` for THIS repo so callers always get a
-     * sensible result. Hydrates each hit's StoredCheckpoint from the authoritative
-     * node:sqlite store (the hit's repoId doubles as that repo's stateDir), then
-     * MMR-dedupes the merged set.
-     */
-    async searchAsync(sessionId, query, k = 3, opts = {}) {
-        const sid = normalizeSessionId(sessionId);
-        const qv = this.embedder.embed(query);
-        // repoId filter: explicit opts.repoId wins; else this repo unless crossRepo.
-        const repoId = opts.repoId ?? (opts.crossRepo ? undefined : this.repoId);
-        let indexHits = [];
-        try {
-            await initVectorIndex();
-            indexHits = await vectorIndexSearch(qv, { k: Math.max(k * 2, k), repoId });
-        }
-        catch {
-            indexHits = [];
-        }
-        if (indexHits.length === 0) {
-            // Index empty/unavailable → synchronous per-session fallback (this repo).
-            return this.search(sid, query, k);
-        }
-        // Hydrate each index hit from the authoritative node:sqlite store. repoId is
-        // that repo's stateDir, so cross-repo hits resolve against their own store.
-        // Tag cross-repo hits with their source repoId so the recall block can label
-        // them ("from repo <name>"); same-repo hits stay unlabeled.
-        const selfRepo = this.repoId;
-        const hydrated = [];
-        for (const h of indexHits) {
-            const cp = getCheckpoint(h.sessionId, h.checkpointId, h.repoId);
-            if (cp && cp.dedupStatus !== "removed") {
-                const crossRepo = opts.crossRepo && selfRepo && h.repoId && h.repoId !== selfRepo;
-                hydrated.push({ checkpoint: cp, score: h.score, repoId: crossRepo ? h.repoId : undefined });
-            }
-        }
-        if (hydrated.length === 0)
-            return this.search(sid, query, k);
-        // MMR-dedupe the merged candidate set for diversity (mirrors sync search).
-        const mmrItems = hydrated.map((h) => ({
-            item: h,
-            vector: h.checkpoint.embedding,
-            relevance: h.score,
-        }));
-        return mmrRerank(mmrItems, k, this.cfg.MMR_LAMBDA);
-    }
-    /**
-     * Serve the RAPTOR tree for a query (Fix D): rehydrate the persisted tree and
-     * return its staged-expansion leaf hits as SearchHits. Returns [] when no tree
-     * exists (small sessions — flat search remains the path). Best-effort/non-fatal.
-     */
-    raptorSearchHits(sid, query, k) {
-        const t0 = Date.now();
-        try {
-            // S25 gate (a): honor the shadow contract at SERVE time. The tree is still
-            // built + persisted (logging-only) but NOT merged into recall while
-            // RAPTOR_SHADOW_MODE is anything other than "false".
-            if (isShadowMode())
-                return [];
-            const tree = rehydrateRaptorTree(sid, this.stateDir);
-            if (!tree || !tree.rootId)
-                return [];
-            // S25 gate (b): freshness + fallback guards. Skip a tree built before the
-            // newest checkpoint (stale → may reference trimmed/deduped leaves) or one
-            // whose root is a budget-exhausted extractive fallback (level 99).
-            if (tree.timedOut)
-                return [];
-            const maxTs = maxCheckpointTimestamp(sid, this.stateDir);
-            if (tree.builtAt && tree.builtAt < maxTs)
-                return [];
-            const leafIds = stagedExpansion(query, tree, {
-                embedder: this.embedder,
-                k,
-                topM: this.cfg.RAPTOR_CLUSTERS_PER_LEVEL,
-                mmrLambda: this.cfg.MMR_LAMBDA,
-            });
-            if (leafIds.length === 0)
-                return [];
-            const all = listCheckpoints(sid, this.stateDir).filter((cp) => cp.dedupStatus !== "removed");
-            const qv = this.embedder.embed(query);
-            const hits = [];
-            for (const id of leafIds) {
-                const cp = all.find((c) => c.checkpointId === id);
-                if (cp)
-                    hits.push({ checkpoint: cp, score: cosineSimilarity(qv, cp.embedding) });
-            }
-            // S25 monitoring: emit a raptor_serve decision so canary.ts can track
-            // p95 latency + the tier's live traffic (non-fatal, best-effort).
-            this.record("RAPTOR", hits.length > 0 ? "new" : "mark_only", `leaves=${leafIds.length}`, Date.now() - t0);
-            return hits;
-        }
-        catch {
-            return [];
-        }
-    }
-    /**
-     * SemDeDup offline cleanup (Sprint 12, QA #17): within a session, mark the
-     * lower-quality row of any pair scoring cosine > `threshold` as
-     * `dedup_status='removed'` (kept, not deleted — retrieval excludes it). Keeps
-     * the row with the higher `tokenEstimate` (more context preserved). Runs as a
-     * single scan; idempotent (re-running skips already-removed rows).
-     *
-     * Returns the number of rows marked removed.
-     */
-    semDedup(sessionId, threshold = this.cfg.SEMDEDUP_COSINE) {
-        const sid = normalizeSessionId(sessionId);
-        const cps = listCheckpoints(sid, this.stateDir).filter((c) => c.dedupStatus !== "removed");
-        let removed = 0;
-        for (let i = 0; i < cps.length; i++) {
-            for (let j = i + 1; j < cps.length; j++) {
-                const a = cps[i];
-                const b = cps[j];
-                if (a.dedupStatus === "removed" || b.dedupStatus === "removed")
-                    continue;
-                if (cosineSimilarity(a.embedding, b.embedding) > threshold) {
-                    // Keep the higher-tokenEstimate row; remove the other.
-                    const keep = a.tokenEstimate >= b.tokenEstimate ? a : b;
-                    const drop = keep === a ? b : a;
-                    setDedupStatus(drop.checkpointId, sid, "removed", this.stateDir);
-                    drop.dedupStatus = "removed";
-                    removed++;
-                }
-            }
-        }
-        return removed;
-    }
-    /**
-     * Dedup sentinel check: has this region already been stored/represented?
-     * Consulted by both the persist path and the recall/inline path.
-     */
-    dedupe(sessionId, regionHashOrText, isText = false) {
-        const sid = normalizeSessionId(sessionId);
-        const hash = isText
-            ? computeRegionHash(regionHashOrText)
-            : regionHashOrText;
-        const state = loadSessionState(sid, this.stateDir);
-        if (state.storedRegionHashes.includes(hash))
-            return true;
-        return listCheckpoints(sid, this.stateDir).some((c) => c.regionHash === hash);
-    }
-    /** Mark a checkpoint as injected into the window (recall dedup). */
-    markInjected(sessionId, checkpointId) {
-        const sid = normalizeSessionId(sessionId);
-        const state = loadSessionState(sid, this.stateDir);
-        if (!state.injectedCheckpointIds.includes(checkpointId)) {
-            state.injectedCheckpointIds.push(checkpointId);
-            saveSessionState(sid, state, this.stateDir);
-        }
-    }
-    /** True if this checkpoint was already injected this session. */
-    wasInjected(sessionId, checkpointId) {
-        const state = loadSessionState(normalizeSessionId(sessionId), this.stateDir);
-        return state.injectedCheckpointIds.includes(checkpointId);
-    }
-    /** Convenience for a raw vector cosine (exposed for tests). */
-    similarity(a, b) {
-        return cosineSimilarity(a, b);
-    }
-    /** All checkpoints for a session (sorted by checkpointId). */
-    list(sessionId) {
-        return listCheckpoints(normalizeSessionId(sessionId), this.stateDir);
-    }
-    /**
-     * Return the n most similar checkpoints to the current (most recent) checkpoint
-     * by cosine similarity. Returns fewer than n if the session has fewer checkpoints.
-     * The current checkpoint itself is excluded from results.
-     */
-    topSimilar(sessionId, n) {
-        const sid = normalizeSessionId(sessionId);
-        const checkpoints = listCheckpoints(sid, this.stateDir);
-        if (checkpoints.length <= 1)
-            return [];
-        // Find the most recent checkpoint (by checkpointId, which is sequential)
-        const ordered = [...checkpoints].sort((a, b) => a.checkpointId.localeCompare(b.checkpointId));
-        const current = ordered[ordered.length - 1];
-        // Score all other checkpoints by similarity to current
-        const scored = ordered
-            .filter((cp) => cp.checkpointId !== current.checkpointId)
-            .map((cp) => ({
-            checkpoint: cp,
-            score: cosineSimilarity(current.embedding, cp.embedding),
-        }))
-            .sort((a, b) => b.score - a.score);
-        return scored.slice(0, n);
-    }
-    /**
-     * Store statistics for status reporting / logging. Returns counts + the last
-     * (highest-numbered) checkpoint, or nulls when the session is empty.
-     */
-    stats(sessionId) {
-        const sid = normalizeSessionId(sessionId);
-        const cps = listCheckpoints(sid, this.stateDir);
-        const state = loadSessionState(sid, this.stateDir);
-        const ordered = [...cps].sort((a, b) => a.checkpointId.localeCompare(b.checkpointId));
-        const last = ordered[ordered.length - 1];
-        const injected = state.injectedCheckpointIds.length;
-        const ds = getDedupStats(this.stateDir);
-        const sessionTok = cps.reduce((s, c) => s + (c.tokenEstimate ?? 0), 0);
-        const sessionOrig = cps.reduce((s, c) => s + (c.originalTokenEstimate ?? 0), 0);
-        // Per-session "tokens saved" = Σ(original − stored) over this session's
-        // stored checkpoints. Deduped adds (whole region discarded, nothing stored)
-        // are counted in the repo-wide meta counter via repoStats(); the per-session
-        // DB sum here covers the rows that exist.
-        const sessionSaved = cps.reduce((s, c) => s + Math.max(0, (c.originalTokenEstimate ?? 0) - (c.tokenEstimate ?? 0)), 0);
-        return {
-            checkpointCount: cps.length,
-            totalTokenEstimate: sessionTok,
-            lastCheckpointId: last?.checkpointId,
-            lastSummary: last?.summary,
-            injectedCount: injected,
-            dedupHitRate: cps.length === 0 ? 0 : injected / cps.length,
-            storageDedupRate: ds.attempts === 0 ? 0 : ds.deduped / ds.attempts,
-            tokensSaved: sessionSaved,
-            originalTokens: sessionOrig,
-            dedupAttempts: ds.attempts,
-            dedupCollapsed: ds.deduped,
-        };
-    }
-    /**
-     * Repo-wide stats — aggregates every session in this store (one per repo).
-     * Cumulative, resumable, cross-device. Surfaces the dashboard's "Repo …"
-     * figures; distinct from {@link stats} (per-session).
-     */
-    repoStats() {
-        return repoStatsFromStore(this.stateDir);
-    }
-    /** Data-safety invariant (Phase 0): regions retained vs bytes permanently deleted. */
-    dataInvariant() {
-        return dataInvariantStats(this.stateDir);
-    }
 }
+// Re-exports (back-compat): existing call sites keep importing from "./vectorStore.js"
+export { vectorSemDedup, vectorDedupe, vectorMarkInjected, vectorWasInjected, vectorSimilarity, vectorList, vectorTopSimilar, vectorStats, vectorRepoStats, vectorDataInvariant, } from "./vector-read.js";
+// Re-exports: vectorSearch / vectorSearchAsync (moved to vector-search.ts)
+export { vectorSearch, vectorSearchAsync } from "./vector-search.js";

package/dist/src/vectorStore.test.js

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { VectorStore, computeRegionHash } from "./vectorStore.js";
+import { VectorStore, computeRegionHash, vectorStats, vectorDedupe, vectorWasInjected, vectorMarkInjected, vectorList, vectorTopSimilar, vectorRepoStats, vectorSearch } from "./vectorStore.js";
 import { TrigramEmbedder, cosineSimilarity, l2Normalize, defaultEmbedder, } from "./embedder.js";
 import { normalizeSessionId, decompressSmart } from "./store.js";
 const baseTmp = mkdtempSync(join(tmpdir(), "mc-test-"));
@@ -45,7 +45,7 @@ test("add then search returns the planted checkpoint top-1", () => {
         tokenEstimate: 1200,
         timestamp: 1000,
     });
-    const hits = s.search("sess_abc", "src/compact.ts truncate helper", 3);
+    const hits = vectorSearch(s, "sess_abc", "src/compact.ts truncate helper", 3);
     assert.equal(hits.length, 1);
     assert.ok(hits[0].score > 0.5);
     assert.equal(hits[0].checkpoint.summary.includes("src/compact.ts"), true);
@@ -68,7 +68,7 @@ test("dedup by regionHash: identical region is not double-stored", () => {
     assert.equal(r1.deduped, false);
     assert.equal(r2.deduped, true);
     assert.equal(r1.checkpoint.checkpointId, r2.checkpoint.checkpointId);
-    assert.equal(s.search("sess_dup", "anything", 10).length, 1);
+    assert.equal(vectorSearch(s, "sess_dup", "anything", 10).length, 1);
 });
 test("dedup cascade: summaryHash catches same-topic incremental compactions", () => {
     const s = store();
@@ -100,7 +100,7 @@ test("dedup cascade: summaryHash dedup still stores only one checkpoint", () =>
     const ts = "some topic summary that is identical";
     s.add({ sessionId: "sess_sh2", summary, topicSummary: ts, regionText: "region a", timestamp: 1 });
     s.add({ sessionId: "sess_sh2", summary, topicSummary: ts, regionText: "region b", timestamp: 2 });
-    assert.equal(s.stats("sess_sh2").checkpointCount, 1);
+    assert.equal(vectorStats(s, "sess_sh2").checkpointCount, 1);
 });
 test("dedupe() sentinel returns true for a stored region", () => {
     const s = store();
@@ -112,8 +112,8 @@ test("dedupe() sentinel returns true for a stored region", () => {
         regionText: region,
         timestamp: 1,
     });
-    assert.equal(s.dedupe("sess_sent", hash), true);
-    assert.equal(s.dedupe("sess_sent", "deadbeef"), false);
+    assert.equal(vectorDedupe(s, "sess_sent", hash), true);
+    assert.equal(vectorDedupe(s, "sess_sent", "deadbeef"), false);
 });
 test("near-duplicate collapse keeps only the top of a near-identical pair", () => {
     const s = store();
@@ -129,7 +129,7 @@ test("near-duplicate collapse keeps only the top of a near-identical pair", () =
         regionText: "user investigated src/compact.ts and added a truncate helper for the summaries",
         timestamp: 2,
     });
-    const hits = s.search("sess_nd", "user investigated src/compact.ts and added a truncate helper for summaries", 5);
+    const hits = vectorSearch(s, "sess_nd", "user investigated src/compact.ts and added a truncate helper for summaries", 5);
     assert.equal(hits.length, 1);
 });
 test("markInjected / wasInjected track injection", () => {
@@ -140,9 +140,9 @@ test("markInjected / wasInjected track injection", () => {
         regionText: "inject region",
         timestamp: 1,
     });
-    assert.equal(s.wasInjected("sess_inj", r.checkpoint.checkpointId), false);
-    s.markInjected("sess_inj", r.checkpoint.checkpointId);
-    assert.equal(s.wasInjected("sess_inj", r.checkpoint.checkpointId), true);
+    assert.equal(vectorWasInjected(s, "sess_inj", r.checkpoint.checkpointId), false);
+    vectorMarkInjected(s, "sess_inj", r.checkpoint.checkpointId);
+    assert.equal(vectorWasInjected(s, "sess_inj", r.checkpoint.checkpointId), true);
 });
 test("normalizeSessionId handles null, prefixed, and uuid forms", () => {
     assert.match(normalizeSessionId("sess_abc"), /^sess_/);
@@ -177,7 +177,7 @@ test("checkpoints survive a fresh store instance (on-disk)", () => {
         timestamp: 1,
     });
     const s2 = new VectorStore({ dedupSim: 0.9, stateDir: dir }); // new instance, same disk state
-    const hits = s2.search("sess_persist", "persist region text", 3);
+    const hits = vectorSearch(s2, "sess_persist", "persist region text", 3);
     assert.equal(hits.length, 1);
     assert.equal(hits[0].checkpoint.summary, "persisted");
 });
@@ -187,7 +187,7 @@ test("corrupt checkpoint file falls back to empty (no throw)", () => {
     const file = join(dir, "sess_corrupt.checkpoints.json.gz");
     writeFileSync(file, Buffer.from("not a gzip"));
     const s = new VectorStore({ dedupSim: 0.9, stateDir: dir });
-    assert.equal(s.search("sess_corrupt", "q", 3).length, 0);
+    assert.equal(vectorSearch(s, "sess_corrupt", "q", 3).length, 0);
 });
 test("stats reports counts, last checkpoint, and dedup rate", () => {
     const s = store();
@@ -205,14 +205,14 @@ test("stats reports counts, last checkpoint, and dedup rate", () => {
         tokenEstimate: 700,
         timestamp: 2,
     });
-    const st1 = s.stats("sess_stats");
+    const st1 = vectorStats(s, "sess_stats");
     assert.equal(st1.checkpointCount, 2);
     assert.equal(st1.lastCheckpointId, "chkpt_002");
     assert.equal(st1.totalTokenEstimate, 1200);
     assert.equal(st1.injectedCount, 0);
     assert.equal(st1.dedupHitRate, 0);
-    s.markInjected("sess_stats", "chkpt_001");
-    const st2 = s.stats("sess_stats");
+    vectorMarkInjected(s, "sess_stats", "chkpt_001");
+    const st2 = vectorStats(s, "sess_stats");
     assert.equal(st2.injectedCount, 1);
     assert.ok(Math.abs(st2.dedupHitRate - 0.5) < 1e-9);
 });
@@ -223,7 +223,7 @@ test("tokensSaved = original − stored per session; deduped add saves the whole
     //   cp2: orig 3000, stored 700 → saved 2300
     s.add({ sessionId: "sess_saved", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, originalTokenEstimate: 2000, timestamp: 1 });
     s.add({ sessionId: "sess_saved", summary: "beta", regionText: "region beta text", tokenEstimate: 700, originalTokenEstimate: 3000, timestamp: 2 });
-    const st = s.stats("sess_saved");
+    const st = vectorStats(s, "sess_saved");
     assert.equal(st.totalTokenEstimate, 1200, "Σ stored summaries");
     assert.equal(st.originalTokens, 5000, "Σ original region tokens");
     assert.equal(st.tokensSaved, 3800, "per-session saved = Σ(original − stored) = 1500 + 2300");
@@ -234,14 +234,14 @@ test("tokensSaved = original − stored per session; deduped add saves the whole
     // dedupCollapsed bumps, and no new checkpoint row is created.
     const deduped = s.add({ sessionId: "sess_saved", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, originalTokenEstimate: 2000, timestamp: 3 });
     assert.ok(deduped.deduped, "identical region should dedup");
-    const st3 = s.stats("sess_saved");
+    const st3 = vectorStats(s, "sess_saved");
     // Per-session DB sum only covers stored rows (deduped adds create no row), so
     // the per-session figure is unchanged; the deduped save lands in the repo meta.
     assert.equal(st3.tokensSaved, 3800, "per-session DB sum unchanged by deduped add");
     assert.equal(st3.dedupCollapsed, 1, "deduped collapse counted");
     assert.equal(st3.dedupAttempts, 3);
     // Repo cumulative counter DID capture the deduped region's full original size.
-    assert.equal(s.repoStats().tokensSaved, 3800 + 2000, "repo saved includes deduped original");
+    assert.equal(vectorRepoStats(s).tokensSaved, 3800 + 2000, "repo saved includes deduped original");
 });
 test("repoStats aggregates every session + counts deduped original tokens", () => {
     const dir = join(baseTmp, `repo-${counter++}`);
@@ -249,7 +249,7 @@ test("repoStats aggregates every session + counts deduped original tokens", () =
     const b = new VectorStore({ dedupSim: 0.9, stateDir: dir }); // same disk store, diff instance
     a.add({ sessionId: "sess_a", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, originalTokenEstimate: 2000, timestamp: 1 });
     b.add({ sessionId: "sess_b", summary: "beta", regionText: "region beta text", tokenEstimate: 700, originalTokenEstimate: 3000, timestamp: 2 });
-    const repo = a.repoStats();
+    const repo = vectorRepoStats(a);
     assert.equal(repo.checkpointCount, 2, "checkpoints across both sessions");
     assert.equal(repo.sessionCount, 2, "two distinct sessions");
     assert.equal(repo.totalTokenEstimate, 1200, "Σ stored");
@@ -259,7 +259,7 @@ test("repoStats aggregates every session + counts deduped original tokens", () =
     // A deduped add into sess_a: whole original region saved, no new row.
     const deduped = a.add({ sessionId: "sess_a", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, originalTokenEstimate: 2000, timestamp: 3 });
     assert.ok(deduped.deduped);
-    const repo2 = a.repoStats();
+    const repo2 = vectorRepoStats(a);
     assert.equal(repo2.tokensSaved, 3800 + 2000, "deduped collapse adds full original region to repo saved");
     assert.equal(repo2.dedupCollapsed, 1);
     assert.equal(repo2.checkpointCount, 2, "still two stored checkpoints");
@@ -289,7 +289,7 @@ test("whitespace-variant region is deduplicated", () => {
         timestamp: 2,
     });
     assert.equal(r2.deduped, true, "whitespace-variant should be deduplicated");
-    assert.equal(s.stats("sess_ws").checkpointCount, 1, "only one checkpoint stored");
+    assert.equal(vectorStats(s, "sess_ws").checkpointCount, 1, "only one checkpoint stored");
 });
 test("topSimilar returns n most similar checkpoints to the current (most recent)", () => {
     const s = store();
@@ -313,7 +313,7 @@ test("topSimilar returns n most similar checkpoints to the current (most recent)
         regionText: "fix the buffer overflow in src/compact.ts by adding a bounds check before truncate",
         timestamp: 3,
     });
-    const hits = s.topSimilar("sess_top", 10);
+    const hits = vectorTopSimilar(s, "sess_top", 10);
     assert.equal(hits.length, 2); // two other checkpoints
     // The compact.ts checkpoint should rank above the guitar checkpoint
     assert.equal(hits[0].checkpoint.summary, "compact");
@@ -334,20 +334,20 @@ test("topSimilar excludes the current checkpoint itself", () => {
         regionText: "alpha region text two",
         timestamp: 2,
     });
-    const hits = s.topSimilar("sess_self", 5);
+    const hits = vectorTopSimilar(s, "sess_self", 5);
     assert.equal(hits.length, 1);
     assert.notEqual(hits[0].checkpoint.checkpointId, "chkpt_002"); // not the current
 });
 test("topSimilar returns empty for sessions with 0 or 1 checkpoints", () => {
     const s = store();
-    assert.deepEqual(s.topSimilar("sess_none", 5), []);
+    assert.deepEqual(vectorTopSimilar(s, "sess_none", 5), []);
     s.add({
         sessionId: "sess_one",
         summary: "solo",
         regionText: "only checkpoint",
         timestamp: 1,
     });
-    assert.deepEqual(s.topSimilar("sess_one", 5), []);
+    assert.deepEqual(vectorTopSimilar(s, "sess_one", 5), []);
 });
 test("topSimilar respects the n limit", () => {
     const s = store();
@@ -366,12 +366,12 @@ test("topSimilar respects the n limit", () => {
             timestamp: i + 1,
         });
     }
-    const hits = s.topSimilar("sess_limit", 2);
+    const hits = vectorTopSimilar(s, "sess_limit", 2);
     assert.equal(hits.length, 2);
 });
 test("stats on empty session returns zeros and nulls", () => {
     const s = store();
-    const st = s.stats("sess_empty");
+    const st = vectorStats(s, "sess_empty");
     assert.equal(st.checkpointCount, 0);
     assert.equal(st.lastCheckpointId, undefined);
     assert.equal(st.totalTokenEstimate, 0);
@@ -395,7 +395,7 @@ test("L0 content-hash dedup: identical content under different regionText collap
     assert.equal(r1.deduped, false);
     assert.equal(r2.deduped, true);
     assert.equal(r2.reason, "contentHash");
-    assert.equal(s.list("sess_l0").length, 1);
+    assert.equal(vectorList(s, "sess_l0").length, 1);
 });
 test("L0 content-hash dedup stores both hash fields and bumps timestamp on hit", () => {
     const s = store();
@@ -409,7 +409,7 @@ test("L0 content-hash dedup stores both hash fields and bumps timestamp on hit",
     });
     assert.equal(r2.deduped, true);
     assert.equal(r2.reason, "contentHash");
-    const cp = s.list("sess_l0ts")[0];
+    const cp = vectorList(s, "sess_l0ts")[0];
     assert.equal(cp.contentHash?.length, 64);
     assert.equal(cp.contentHash2?.length, 64);
     assert.equal(cp.contentHashVersion, 1);
@@ -419,7 +419,7 @@ test("compressed_original roundtrips through versioned compression", () => {
     const s = store();
     const raw = "raw region text preserved for audit and replay";
     s.add({ sessionId: "sess_co", summary: "x", regionText: raw, timestamp: 1 });
-    const cp = s.list("sess_co")[0];
+    const cp = vectorList(s, "sess_co")[0];
     assert.ok(cp.compressedOriginal instanceof Buffer);
     const restored = decompressSmart(cp.compressedOriginal).toString("utf-8");
     assert.equal(restored, raw);
@@ -465,14 +465,14 @@ test("L1 catches a one-word-diff near-duplicate that L0 misses", () => {
     assert.equal(r1.deduped, false);
     assert.equal(r2.deduped, true);
     assert.equal(r2.reason, "l1MinHash");
-    assert.equal(s.list("sess_l1").length, 1);
+    assert.equal(vectorList(s, "sess_l1").length, 1);
 });
 test("L1 does NOT falsely dedup genuinely different content", () => {
     const s = store();
     s.add({ sessionId: "sess_l1b", summary: "a", regionText: "the database migration added three indexes", timestamp: 1 });
     const r2 = s.add({ sessionId: "sess_l1b", summary: "b", regionText: "the frontend added a dark mode toggle", timestamp: 2 });
     assert.equal(r2.deduped, false);
-    assert.equal(s.list("sess_l1b").length, 2);
+    assert.equal(vectorList(s, "sess_l1b").length, 2);
 });
 test("cleanup", () => {
     rmSync(baseTmp, { recursive: true, force: true });