pi-mega-compact 0.8.24 → 0.8.26

package/dist/src/store/sqlite/turns.js

@@ -0,0 +1,179 @@
+/**
+ * turns.ts — S43 per-turn vector + conversation tracking.
+ *
+ * The relational spine for per-turn + per-conversation memories:
+ *   - `turns`: one row per turn_end (metrics + epoch link + conversation id)
+ *   - `turn_recall`: which checkpoints/cluster summaries were injected at a turn
+ *   - `conversation_branches`: fork registry (parent → child at a turn point)
+ *
+ * `conversationId` (on SessionState) groups turns across pi session resumes;
+ * `/clear` or any fresh root generates a new one via `newConversationId()`.
+ *
+ * `forkConversation(parent, forkTurnId)` copies a parent conversation's
+ * recall state at `forkTurnId` into a fresh conversation's injected-set, so a
+ * forked session starts with exactly the context conversation X had at turn N
+ * (a recall-fork, not a live-window replay — see docs/specs/s48-per-turn-vector-tracking.md).
+ *
+ * No network. Pure SQLite (PREVENT-PI-004). All queries parameterized (PREVENT-002).
+ */
+import { randomBytes } from "node:crypto";
+import { openStore, withTx } from "./utils.js";
+import { getStateDir, normalizeSessionId } from "../../store.js";
+import { loadSessionState, saveSessionState } from "./session-state.js";
+/** Generate a new conversation id (`conv_` + 16 hex). */
+export function newConversationId() {
+    return `conv_${randomBytes(8).toString("hex")}`;
+}
+function rowToTurn(r) {
+    return {
+        id: r.id,
+        conversationId: r.conversation_id,
+        sessionId: r.session_id,
+        turnIndex: r.turn_index,
+        role: r.role ?? null,
+        startedAt: r.started_at,
+        endedAt: r.ended_at ?? null,
+        ctxTokens: r.ctx_tokens ?? null,
+        ctxPercent: r.ctx_percent ?? null,
+        pressureBand: r.pressure_band ?? null,
+        modelId: r.model_id ?? null,
+        epochId: r.epoch_id ?? null,
+    };
+}
+/**
+ * Upsert a turn row at turn_end. Returns the turn id. `startedAt` defaults to
+ * now (the turn_start write can update it; turn_end sets ended_at + metrics).
+ * Idempotent on (session_id, turn_index) — re-upserting overwrites metrics.
+ */
+export function recordTurn(input, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(input.sessionId);
+    const startedAt = input.startedAt ?? Date.now();
+    db.prepare(`INSERT INTO turns (conversation_id, session_id, turn_index, role, started_at,
+                         ended_at, ctx_tokens, ctx_percent, pressure_band, model_id, epoch_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(session_id, turn_index) DO UPDATE SET
+       conversation_id = excluded.conversation_id,
+       role = COALESCE(excluded.role, role),
+       started_at = COALESCE(excluded.started_at, started_at),
+       ended_at = COALESCE(excluded.ended_at, ended_at),
+       ctx_tokens = COALESCE(excluded.ctx_tokens, ctx_tokens),
+       ctx_percent = COALESCE(excluded.ctx_percent, ctx_percent),
+       pressure_band = COALESCE(excluded.pressure_band, pressure_band),
+       model_id = COALESCE(excluded.model_id, model_id),
+       epoch_id = COALESCE(excluded.epoch_id, epoch_id)`).run(input.conversationId, sid, input.turnIndex, input.role ?? null, startedAt, input.endedAt ?? null, input.ctxTokens ?? null, input.ctxPercent ?? null, input.pressureBand ?? null, input.modelId ?? null, input.epochId ?? null);
+    const row = db
+        .prepare("SELECT id FROM turns WHERE session_id = ? AND turn_index = ?")
+        .get(sid, input.turnIndex);
+    return row.id;
+}
+/**
+ * Record what was recalled at a turn. Called from recallAndInline with the
+ * resolved toInject list — each hit becomes a turn_recall row with its source
+ * path + score. RAPTOR cluster hits carry raptorLevel. Best-effort + non-fatal.
+ */
+export function recordTurnRecall(turnId, hits, stateDir = getStateDir()) {
+    if (hits.length === 0)
+        return;
+    const db = openStore(stateDir);
+    const stmt = db.prepare(`INSERT INTO turn_recall (turn_id, checkpoint_id, score, source, raptor_level)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT(turn_id, checkpoint_id) DO UPDATE SET
+       score = excluded.score, source = excluded.source,
+       raptor_level = excluded.raptor_level`);
+    withTx(db, () => {
+        for (const h of hits) {
+            stmt.run(turnId, h.checkpointId, h.score, h.source, h.raptorLevel ?? null);
+        }
+    });
+}
+/** Get a turn by conversation id + turn index (the lookup a fork uses). */
+export function getTurn(conversationId, turnIndex, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db
+        .prepare(`SELECT * FROM turns WHERE conversation_id = ? AND turn_index = ?`)
+        .get(conversationId, turnIndex);
+    return row ? rowToTurn(row) : null;
+}
+/** Get a turn by its global id. */
+export function getTurnById(turnId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const row = db.prepare("SELECT * FROM turns WHERE id = ?").get(turnId);
+    return row ? rowToTurn(row) : null;
+}
+/** All turn_recall rows for a turn (what was injected at that turn). */
+export function listTurnRecall(turnId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const rows = db
+        .prepare(`SELECT id, turn_id, checkpoint_id, score, source, raptor_level
+       FROM turn_recall WHERE turn_id = ? ORDER BY score DESC`)
+        .all(turnId);
+    return rows.map((r) => ({
+        id: r.id,
+        turnId: r.turn_id,
+        checkpointId: r.checkpoint_id,
+        score: r.score,
+        source: r.source,
+        raptorLevel: r.raptor_level ?? null,
+    }));
+}
+/** All turns in a conversation, ascending by turn_index. */
+export function listConversationTurns(conversationId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const rows = db
+        .prepare(`SELECT * FROM turns WHERE conversation_id = ? ORDER BY turn_index ASC`)
+        .all(conversationId);
+    return rows.map(rowToTurn);
+}
+/** Resolve a session's conversation id, generating + persisting one if none.
+ *  A resumed session inherits its existing conversationId from session_state. */
+export function ensureConversationId(sessionId, stateDir = getStateDir()) {
+    const st = loadSessionState(sessionId, stateDir);
+    if (st.conversationId)
+        return st.conversationId;
+    const conv = newConversationId();
+    saveSessionState(sessionId, {
+        ...st,
+        conversationId: conv,
+    }, stateDir);
+    return conv;
+}
+/**
+ * Fork a conversation at `forkTurnId`: create a new conversation id, record the
+ * branch lineage, and return the parent's recall set at that turn (the
+ * checkpoint_ids + scores that were injected) so the caller can seed the forked
+ * session's injected-set with exactly that context.
+ *
+ * Returns the new conversation id + the recall-set rows to replay. The caller
+ * (the engine/extension) is responsible for marking those checkpoint_ids as
+ * injected in the new session's session_state so they're not re-recalled.
+ */
+export function forkConversation(parentConversationId, forkTurnId, stateDir = getStateDir()) {
+    const childId = newConversationId();
+    const db = openStore(stateDir);
+    withTx(db, () => {
+        db.prepare(`INSERT INTO conversation_branches
+         (conversation_id, parent_conversation_id, fork_turn_id, created_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(conversation_id) DO NOTHING`).run(childId, parentConversationId, forkTurnId, Date.now());
+    });
+    // Replay set: the parent's injected checkpoints at the fork turn.
+    const recalled = listTurnRecall(forkTurnId, stateDir);
+    return { conversationId: childId, recalled };
+}
+/** Clear turn tracking rows for a session (tests / DR). */
+export function clearTurns(sessionId, stateDir = getStateDir()) {
+    const db = openStore(stateDir);
+    const sid = normalizeSessionId(sessionId);
+    withTx(db, () => {
+        const turnIds = db
+            .prepare("SELECT id FROM turns WHERE session_id = ?")
+            .all(sid);
+        const ids = turnIds.map((t) => t.id);
+        if (ids.length > 0) {
+            const placeholders = ids.map(() => "?").join(",");
+            db.prepare(`DELETE FROM turn_recall WHERE turn_id IN (${placeholders})`).run(...ids);
+        }
+        db.prepare("DELETE FROM turns WHERE session_id = ?").run(sid);
+    });
+}

package/dist/src/store/sqlite/turns.test.js

@@ -0,0 +1,183 @@
+/**
+ * turns.test.ts — S43 per-turn + conversation tracking tests.
+ *
+ * No network. Real stores with temp state dirs.
+ */
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openStore } from "./utils.js";
+import { recordTurn, recordTurnRecall, getTurn, getTurnById, listTurnRecall, listConversationTurns, ensureConversationId, forkConversation, newConversationId, clearTurns, } from "./turns.js";
+import { loadSessionState, saveSessionState } from "./session-state.js";
+let tmpDir;
+let counter = 0;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mc-turns-"));
+});
+afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+function stateDir() {
+    return join(tmpDir, `run-${counter++}`);
+}
+// ─── 1. recordTurn upserts + getTurn round-trip ────────────────────────────
+test("S43-1: recordTurn inserts/updates + getTurn finds by conv+index", () => {
+    const sd = stateDir();
+    openStore(sd);
+    const conv = newConversationId();
+    const id = recordTurn({
+        conversationId: conv,
+        sessionId: "sess-1",
+        turnIndex: 3,
+        endedAt: 1000,
+        ctxTokens: 12000,
+        ctxPercent: 42.5,
+        pressureBand: "mid",
+        modelId: "claude-fable-5",
+    }, sd);
+    assert.ok(id > 0, "turn id returned");
+    const t = getTurn(conv, 3, sd);
+    assert.ok(t, "turn found");
+    assert.equal(t.conversationId, conv);
+    assert.equal(t.turnIndex, 3);
+    assert.equal(t.ctxTokens, 12000);
+    assert.equal(t.ctxPercent, 42.5);
+    assert.equal(t.pressureBand, "mid");
+    assert.equal(t.modelId, "claude-fable-5");
+    assert.equal(t.endedAt, 1000);
+    // Re-record (upsert) with additional metrics — COALESCE preserves started_at.
+    const id2 = recordTurn({
+        conversationId: conv,
+        sessionId: "sess-1",
+        turnIndex: 3,
+        startedAt: 900,
+        ctxTokens: 12500,
+    }, sd);
+    assert.equal(id2, id, "same turn id on upsert");
+    const t2 = getTurn(conv, 3, sd);
+    assert.equal(t2.ctxTokens, 12500, "metrics updated");
+    assert.equal(t2.startedAt, 900, "started_at set on second write");
+});
+// ─── 2. recordTurnRecall + listTurnRecall ───────────────────────────────────
+test("S43-2: recordTurnRecall stores provenance + listTurnRecall returns it", () => {
+    const sd = stateDir();
+    openStore(sd);
+    const conv = newConversationId();
+    const turnId = recordTurn({
+        conversationId: conv,
+        sessionId: "sess-1",
+        turnIndex: 1,
+    }, sd);
+    recordTurnRecall(turnId, [
+        { checkpointId: "chkpt_003", score: 0.91, source: "flat" },
+        { checkpointId: "r1_0", score: 0.78, source: "raptor", raptorLevel: 1 },
+        { checkpointId: "chkpt_007", score: 0.65, source: "cross-repo" },
+    ], sd);
+    const recalls = listTurnRecall(turnId, sd);
+    assert.equal(recalls.length, 3);
+    assert.equal(recalls[0].checkpointId, "chkpt_003", "sorted by score desc");
+    assert.equal(recalls[0].score, 0.91);
+    const raptorHit = recalls.find((r) => r.source === "raptor");
+    assert.ok(raptorHit, "raptor hit present");
+    assert.equal(raptorHit.raptorLevel, 1);
+    assert.equal(raptorHit.checkpointId, "r1_0");
+    // Re-record with a changed score → upsert, no duplicate.
+    recordTurnRecall(turnId, [{ checkpointId: "chkpt_003", score: 0.95, source: "flat" }], sd);
+    const recalls2 = listTurnRecall(turnId, sd);
+    assert.equal(recalls2.length, 3, "no duplicate on re-record");
+    const updated = recalls2.find((r) => r.checkpointId === "chkpt_003");
+    assert.equal(updated.score, 0.95, "score updated");
+});
+// ─── 3. listConversationTurns ───────────────────────────────────────────────
+test("S43-3: listConversationTurns returns turns in order", () => {
+    const sd = stateDir();
+    openStore(sd);
+    const conv = newConversationId();
+    for (let i = 1; i <= 4; i++) {
+        recordTurn({
+            conversationId: conv,
+            sessionId: "sess-1",
+            turnIndex: i,
+            endedAt: i * 100,
+        }, sd);
+    }
+    const turns = listConversationTurns(conv, sd);
+    assert.equal(turns.length, 4);
+    assert.deepEqual(turns.map((t) => t.turnIndex), [1, 2, 3, 4]);
+});
+// ─── 4. ensureConversationId persists + is stable across resumes ───────────
+test("S43-4: ensureConversationId generates once, persists, survives reload", () => {
+    const sd = stateDir();
+    openStore(sd);
+    const sid = "sess-resume";
+    // First call generates + persists.
+    const conv1 = ensureConversationId(sid, sd);
+    assert.ok(conv1.startsWith("conv_"), "generated id has prefix");
+    // Second call (simulated resume) returns the same id — reads session_state.
+    const conv2 = ensureConversationId(sid, sd);
+    assert.equal(conv2, conv1, "stable across resumes");
+    // A different session gets a different conversation id.
+    const conv3 = ensureConversationId("sess-other", sd);
+    assert.notEqual(conv3, conv1);
+});
+// ─── 5. forkConversation records lineage + returns recall set ──────────────
+test("S43-5: forkConversation creates child + returns parent's recall set", () => {
+    const sd = stateDir();
+    openStore(sd);
+    const parent = newConversationId();
+    // Parent conversation: turn 1 with 2 recalled checkpoints.
+    const turnId = recordTurn({
+        conversationId: parent,
+        sessionId: "sess-parent",
+        turnIndex: 1,
+    }, sd);
+    recordTurnRecall(turnId, [
+        { checkpointId: "chkpt_001", score: 0.9, source: "flat" },
+        { checkpointId: "chkpt_002", score: 0.7, source: "flat" },
+    ], sd);
+    // Fork at turn 1.
+    const { conversationId: child, recalled } = forkConversation(parent, turnId, sd);
+    assert.ok(child.startsWith("conv_"), "child is a conversation id");
+    assert.notEqual(child, parent, "child differs from parent");
+    assert.equal(recalled.length, 2, "parent's recall set returned for replay");
+    assert.ok(recalled.some((r) => r.checkpointId === "chkpt_001"), "includes parent's recalled checkpoint");
+    // The child conversation is recorded as a branch.
+    const branches = openStore(sd).prepare("SELECT parent_conversation_id, fork_turn_id FROM conversation_branches WHERE conversation_id = ?").get(child);
+    assert.equal(branches.parent_conversation_id, parent);
+    assert.equal(branches.fork_turn_id, turnId);
+});
+// ─── 6. clearTurns removes turns + their recall rows for a session ──────────
+test("S43-6: clearTurns removes turns + cascade turn_recall", () => {
+    const sd = stateDir();
+    openStore(sd);
+    const conv = newConversationId();
+    const turnId = recordTurn({
+        conversationId: conv,
+        sessionId: "sess-clear",
+        turnIndex: 1,
+    }, sd);
+    recordTurnRecall(turnId, [{ checkpointId: "x", score: 0.5, source: "flat" }], sd);
+    assert.equal(listTurnRecall(turnId, sd).length, 1);
+    clearTurns("sess-clear", sd);
+    assert.equal(getTurnById(turnId, sd), null, "turn gone");
+    assert.equal(listTurnRecall(turnId, sd).length, 0, "recall rows cascaded");
+});
+// ─── 7. conversation id survives across SessionState save/load ──────────────
+test("S43-7: conversationId round-trips through SessionState", () => {
+    const sd = stateDir();
+    openStore(sd);
+    const sid = "sess-rt";
+    // Save a state with a conversationId.
+    const conv = "conv_roundtrip";
+    saveSessionState(sid, {
+        injectedCheckpointIds: [],
+        storedRegionHashes: [],
+        conversationId: conv,
+    }, sd);
+    const loaded = loadSessionState(sid, sd);
+    assert.equal(loaded.conversationId, conv, "conversationId persisted");
+    // ensureConversationId picks up the existing one.
+    assert.equal(ensureConversationId(sid, sd), conv, "ensure keeps existing");
+});

package/dist/src/store/sqlite/utils.js

@@ -38,6 +38,17 @@ export function decodeEmbedding(buf) {
 export function jsonText(v) {
     return JSON.stringify(v ?? []);
 }
+/** Safe JSON parse — returns `fallback` on null/undefined/corrupt input. */
+export function safeJson(s, fallback) {
+    if (!s)
+        return fallback;
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return fallback;
+    }
+}
 // In-process cache so the same stateDir reuses one connection (and so a fresh
 // VectorStore over the same dir shares the open DB). Cross-process durability
 // comes from reopening the same file path — proven by the integration test.
@@ -50,7 +61,7 @@ export function openStore(stateDir = getStateDir()) {
         // instead of closeStore) would surface as "database is not open" on the
         // next reuse. Detect and evict so callers never see a dead handle.
         try {
-            existing.prepare("SELECT 1");
+            existing.exec("SELECT 1");
             return existing;
         }
         catch {
@@ -100,9 +111,9 @@ export function rowToCheckpoint(row) {
         summary: row.summary ?? "",
         topicSummary: row.topic_summary ?? undefined,
         summaryHash: row.summary_hash ?? undefined,
-        keyDecisions: row.key_decisions ? JSON.parse(row.key_decisions) : [],
-        nextSteps: row.next_steps ? JSON.parse(row.next_steps) : [],
-        filesModified: row.files_modified ? JSON.parse(row.files_modified) : [],
+        keyDecisions: safeJson(row.key_decisions, []),
+        nextSteps: safeJson(row.next_steps, []),
+        filesModified: safeJson(row.files_modified, []),
         tokenEstimate: row.token_estimate ?? 0,
         originalTokenEstimate: row.original_token_estimate ?? undefined,
         regionHash: row.region_hash ?? "",

package/dist/src/store/sqlite.js

@@ -24,3 +24,4 @@ export * from "./sqlite/game-state.js";
 export * from "./sqlite/game-scores.js";
 export * from "./sqlite/game-achievements.js";
 export * from "./sqlite/perf-samples.js";
+export * from "./sqlite/turns.js";

package/dist/src/store.js

@@ -28,7 +28,7 @@ export function normalizeSessionId(sessionId) {
     if (sessionId.startsWith("sess_"))
         return sessionId;
     if (sessionId.length >= 32 && sessionId.includes("-")) {
-        return `sess_${sessionId.replace(/-/g, "").slice(0, 16)}`;
+        return `sess_${sessionId.replace(/-/g, "").toLowerCase().slice(0, 16)}`;
     }
     return `sess_${sessionId}`;
 }
@@ -64,7 +64,7 @@ export function writeGzJson(path, data) {
 }
 /** Append a checkpoint to the per-session checkpoint file (gzipped). */
 export function appendCheckpoint(cp, stateDir = getStateDir()) {
-    const file = join(stateDir, `${cp.sessionId}.checkpoints.json.gz`);
+    const file = join(stateDir, `${normalizeSessionId(cp.sessionId)}.checkpoints.json.gz`);
     const existing = readGzJson(file, []);
     existing.push(cp);
     writeGzJson(file, existing);

package/dist/src/vector-search-cache.test.js

@@ -0,0 +1,157 @@
+/**
+ * vector-search-cache.test.ts — QA perf/correctness regression tests for the
+ * RAPTOR serve path and the per-session raptorCache.
+ *
+ * Guards two invariants the S42B/S25 wiring introduced:
+ *   (a) Enabling RAPTOR (multilevel ON) never returns FEWER relevant hits than
+ *       flat-only at the same k — no cache-hit loss / MMR starvation.
+ *   (b) The per-search listCheckpoints is shared (not double-loaded): the
+ *       warm-search latency at 200 checkpoints stays under the QA budget.
+ *
+ * No network. Real stores, temp state dirs.
+ */
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { VectorStore, vectorList, vectorSearch } from "./vectorStore.js";
+import { runRaptor } from "./dedup/raptor/index.js";
+import { compactSession } from "./engine.js";
+import { loadDedupConfig } from "./config/dedup.js";
+import { normalizeSessionId } from "./store.js";
+let tmpDir;
+let counter = 0;
+beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mc-vc-"));
+});
+afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+});
+function stateDir() {
+    return join(tmpDir, `run-${counter++}`);
+}
+function cfg(overrides) {
+    return {
+        ...loadDedupConfig(),
+        RAPTOR_ENABLED: true,
+        L0_ENABLED: false,
+        L1_ENABLED: false,
+        L2_ENABLED: true,
+        ...overrides,
+    };
+}
+function msg(text, toolName) {
+    return toolName
+        ? { role: "assistant", text, toolName, input: text, output: text }
+        : { role: "user", text };
+}
+function seedTwoTopics(store, sid, perTopic) {
+    const topics = [
+        "database connection pool postgres query optimizer",
+        "user interface button render react component",
+    ];
+    for (let i = 1; i <= perTopic * 2; i++) {
+        const t = topics[i % 2];
+        compactSession({
+            sessionId: sid,
+            messages: [msg(`${t} checkpoint ${i} alpha beta gamma`), msg(`ack ${i}`, "Edit")],
+            keepFrom: 2,
+            timestamp: i,
+        }, store);
+    }
+}
+// ─── (a) RAPTOR ON never loses hits vs OFF ──────────────────────────────────
+test("QA cache: RAPTOR-ON returns >= flat-only hits at same k (no MMR starvation)", () => {
+    const k = 5;
+    // Build the same session twice (isolated state dirs) so the comparison is
+    // exact: same checkpoints, same embeddings, only the RAPTOR flag differs.
+    const queries = ["database connection pool", "user interface button", "alpha beta gamma"];
+    for (const q of queries) {
+        let offHits = 0;
+        let onHits = 0;
+        for (const raptorOn of [false, true]) {
+            const sd = stateDir();
+            const s = new VectorStore({
+                dedupSim: 0.9,
+                stateDir: sd,
+                config: raptorOn
+                    ? cfg({ RAPTOR_MULTILEVEL_ENABLED: true, RAPTOR_LEAF_EXPANSION: true })
+                    : cfg({ RAPTOR_ENABLED: false }),
+            });
+            const sid = `cache-${q.length}-${raptorOn ? 1 : 0}`;
+            seedTwoTopics(s, sid, 8); // 16 checkpoints, 2 topics
+            if (raptorOn) {
+                const nsid = normalizeSessionId(sid);
+                runRaptor(vectorList(s, nsid).map((cp) => ({
+                    id: cp.checkpointId,
+                    messages: [],
+                    sourceText: cp.normalizedText ?? cp.summary ?? cp.regionHash,
+                    embedding: cp.embedding,
+                })), { stateDir: sd, sessionId: nsid });
+            }
+            process.env.RAPTOR_SHADOW_MODE = raptorOn ? "false" : "true";
+            const hits = vectorSearch(s, sid, q, k);
+            if (raptorOn)
+                onHits = hits.length;
+            else
+                offHits = hits.length;
+        }
+        assert.ok(onHits >= offHits, `RAPTOR ON (${onHits}) >= OFF (${offHits}) for query "${q}"`);
+    }
+});
+// ─── (b) Warm-search latency budget at 200 checkpoints ─────────────────────
+test("QA perf: warm RAPTOR search at 200 checkpoints stays under budget (no double scan)", () => {
+    const sd = stateDir();
+    const s = new VectorStore({
+        dedupSim: 0.9,
+        stateDir: sd,
+        config: cfg({ RAPTOR_MULTILEVEL_ENABLED: true }),
+    });
+    const sid = "perf";
+    seedTwoTopics(s, sid, 100); // 200 checkpoints
+    const nsid = normalizeSessionId(sid);
+    runRaptor(vectorList(s, nsid).map((cp) => ({
+        id: cp.checkpointId,
+        messages: [],
+        sourceText: cp.normalizedText ?? cp.summary ?? cp.regionHash,
+        embedding: cp.embedding,
+    })), { stateDir: sd, sessionId: nsid });
+    process.env.RAPTOR_SHADOW_MODE = "false";
+    // Warm the cache + embedder.
+    vectorSearch(s, sid, "database connection pool", 5);
+    vectorSearch(s, sid, "database connection pool", 5);
+    // Time a burst of warm searches. The double-scan fix keeps this well under
+    // the pre-fix cost. Budget is generous (10ms/search) to avoid CI flake;
+    // the regression it guards is the ~2x blowup from listCheckpoints running
+    // twice per search.
+    const ITERS = 50;
+    const t0 = Date.now();
+    for (let i = 0; i < ITERS; i++)
+        vectorSearch(s, sid, "database connection pool", 5);
+    const perSearch = (Date.now() - t0) / ITERS;
+    assert.ok(perSearch < 10, `warm search ${perSearch.toFixed(2)}ms < 10ms budget (double-scan regression guard)`);
+});
+// ─── (c) No duplicate checkpointIds in merged results ──────────────────────
+test("QA cache: RAPTOR merge produces no duplicate checkpointIds", () => {
+    const sd = stateDir();
+    const s = new VectorStore({
+        dedupSim: 0.9,
+        stateDir: sd,
+        config: cfg({ RAPTOR_MULTILEVEL_ENABLED: true, RAPTOR_LEAF_EXPANSION: false }),
+    });
+    const sid = "dup";
+    seedTwoTopics(s, sid, 8);
+    const nsid = normalizeSessionId(sid);
+    runRaptor(vectorList(s, nsid).map((cp) => ({
+        id: cp.checkpointId,
+        messages: [],
+        sourceText: cp.normalizedText ?? cp.summary ?? cp.regionHash,
+        embedding: cp.embedding,
+    })), { stateDir: sd, sessionId: nsid });
+    process.env.RAPTOR_SHADOW_MODE = "false";
+    const hits = vectorSearch(s, sid, "database connection pool", 8);
+    const ids = hits.map((h) => h.checkpoint.checkpointId);
+    const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
+    assert.equal(dupes.length, 0, "no duplicate checkpointIds in merged results");
+});