pi-mega-compact 0.13.0 → 0.13.2

package/dist/src/ratio.bench.test/_helpers.js

@@ -0,0 +1,198 @@
+/**
+ * Shared helpers for the ratio benchmark split test files.
+ *
+ * Extracted from ratio.bench.test.ts: message builders, tmp-dir lifecycle,
+ * and the generateMessages / generateRealisticConversation / generateNearDuplicates
+ * fixtures used across all benchmark describe blocks.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+export function makeMsg(role, text) {
+    return { role, text };
+}
+export function makeDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "ratio-bench-"));
+}
+/** Generate N messages with controlled repetition. */
+export function generateMessages(n, opts) {
+    const msgs = [];
+    const templates = [
+        "I'm looking at the {file} module. The {component} needs refactoring because {reason}.",
+        "Found a bug in {file}: the {component} doesn't handle {case} correctly. Here's the fix: {fix}",
+        "Let me check the {file} implementation. The {component} uses {pattern} pattern which is fine for now.",
+        "Updated {file} to fix the {component} issue. The {reason} was causing {case}.",
+        "Running tests on {file}. The {component} test covers {case} and {fix}. Looks good.",
+        "The {component} in {file} needs to handle {case}. Currently it just {fix}.",
+        "Reviewed the {file} changes. The {component} refactor looks solid. {reason}.",
+        "Deployed the {component} fix to staging. {file} is now handling {case} correctly.",
+    ];
+    const files = [
+        "src/engine.ts",
+        "src/store.ts",
+        "src/vectorStore.ts",
+        "src/compact.ts",
+        "src/recall.ts",
+    ];
+    const components = [
+        "compression",
+        "dedup",
+        "embedding",
+        "search",
+        "checkpoint",
+        "supersede",
+        "recall",
+    ];
+    const reasons = [
+        "performance",
+        "correctness",
+        "maintainability",
+        "edge case handling",
+        "type safety",
+    ];
+    const cases = [
+        "empty input",
+        "large payloads",
+        "concurrent access",
+        "unicode content",
+        "timeout",
+    ];
+    const fixes = [
+        "added bounds checking",
+        "refactored the loop",
+        "added error handling",
+        "simplified the logic",
+        "added unit tests",
+    ];
+    const patterns = ["singleton", "observer", "strategy", "factory", "builder"];
+    for (let i = 0; i < n; i++) {
+        const template = templates[i % templates.length];
+        const fill = (s) => s
+            .replace("{file}", files[i % files.length])
+            .replace("{component}", components[i % components.length])
+            .replace("{reason}", reasons[i % reasons.length])
+            .replace("{case}", cases[i % cases.length])
+            .replace("{fix}", fixes[i % fixes.length])
+            .replace("{pattern}", patterns[i % patterns.length]);
+        let text;
+        switch (opts.pattern) {
+            case "unique":
+                text = fill(template) + ` [turn ${i}]`;
+                break;
+            case "repetitive":
+                text = fill(templates[i % 5]);
+                break;
+            case "mixed":
+                text =
+                    i % 5 < 3
+                        ? fill(template) + ` [turn ${i}]`
+                        : fill(templates[i % 3]);
+                break;
+            case "code-review":
+                if (i % 4 === 0) {
+                    text = `Reviewing PR #${i}: ${fill(template)}`;
+                }
+                else if (i % 4 === 1) {
+                    text = "```typescript\nfunction handle" + components[i % components.length] + "() {\n  // " + fill(template) + "\n  return result;\n}\n```";
+                }
+                else if (i % 4 === 2) {
+                    text = `LGTM. ${fill(template)} The test coverage looks good.`;
+                }
+                else {
+                    text = `@user requested changes: ${fill(template)}`;
+                }
+                break;
+            case "debug-session":
+                if (i % 6 === 0) {
+                    text = `Error in ${files[i % files.length]}: TypeError: Cannot read property '${components[i % components.length]}' of undefined`;
+                }
+                else if (i % 6 === 1) {
+                    text = `Stack trace:\n  at ${components[i % components.length]} (${files[i % files.length]}:${100 + i}:15)\n  at process (${files[(i + 1) % files.length]}:${50 + i}:3)`;
+                }
+                else if (i % 6 === 2) {
+                    text = `The issue is that ${cases[i % cases.length]} isn't being handled. ${fixes[i % fixes.length]}.`;
+                }
+                else if (i % 6 === 3) {
+                    text = `Applied fix: ${fill(template)}`;
+                }
+                else if (i % 6 === 4) {
+                    text = `Tests passing now. ${reasons[i % reasons.length]}.`;
+                }
+                else {
+                    text = `Committed fix for ${components[i % components.length]}. ${fill(template)}`;
+                }
+                break;
+            default:
+                text = fill(template);
+        }
+        const role = i % 2 === 0 ? "user" : "assistant";
+        msgs.push(makeMsg(role, text));
+    }
+    return msgs;
+}
+/** Generate a large realistic conversation with tool reads, code blocks, discussion. */
+export function generateRealisticConversation(turns) {
+    const msgs = [];
+    for (let i = 0; i < turns; i++) {
+        const phase = i % 8;
+        const mods = ["compression", "dedup", "embedding", "search"];
+        const fns = ["vectorStore.ts", "engine.ts", "compact.ts", "recall.ts"];
+        const issues = ["error handling", "type safety", "performance", "logging"];
+        const bugs = ["null pointer", "type mismatch", "race condition", "memory leak"];
+        switch (phase) {
+            case 0:
+                msgs.push(makeMsg("user", `I need help with the ${mods[i % 4]} module. It's not working correctly.`));
+                break;
+            case 1:
+                msgs.push(makeMsg("assistant", `Let me look at the code. I'll check the ${fns[i % 4]} file.`));
+                break;
+            case 2:
+                msgs.push(makeMsg("tool", `File content of src/${["vectorStore", "engine", "compact", "recall"][i % 4]}.ts:\n${"x".repeat(800 + (i % 5) * 200)}\n// Line ${i * 10}: function ${["search", "compact", "embed", "dedup"][i % 4]}() { ... }`));
+                break;
+            case 3:
+                msgs.push(makeMsg("assistant", `I found the issue. The ${mods[i % 4]} function doesn't handle edge cases properly. Here's what I suggest:\n\n\`\`\`typescript\nfunction fixed${["Search", "Compact", "Embed", "Dedup"][i % 4]}() {\n  if (!input) return null;\n  return process(input);\n}\n\`\`\``));
+                break;
+            case 4:
+                msgs.push(makeMsg("user", `That looks good. Can you also fix the ${issues[i % 4]} while you're at it?`));
+                break;
+            case 5:
+                msgs.push(makeMsg("assistant", `Sure. I've updated the ${issues[i % 4]} as well. The changes affect:\n- src/engine.ts\n- src/store.ts`));
+                break;
+            case 6:
+                msgs.push(makeMsg("user", "Run the tests to make sure nothing is broken."));
+                break;
+            case 7:
+                msgs.push(makeMsg("assistant", `All ${150 + i * 3} tests pass. The fix resolved the ${bugs[i % 4]} issue.`));
+                break;
+        }
+    }
+    return msgs;
+}
+/** Generate near-duplicate messages with controlled edit distance. */
+export function generateNearDuplicates(base, count, editLevel) {
+    const results = [];
+    for (let i = 0; i < count; i++) {
+        switch (editLevel) {
+            case "none":
+                results.push(base);
+                break;
+            case "one-word":
+                results.push(base.replace("bug", ["issue", "defect", "error", "problem"][i % 4]));
+                break;
+            case "minor-rephrase":
+                results.push(base
+                    .replace("Found a bug", [
+                    "Discovered an issue",
+                    "Spotted a defect",
+                    "Located an error",
+                    "Identified a problem",
+                ][i % 4])
+                    .replace("in the", ["in the", "within the", "inside the", "in our"][i % 4]));
+                break;
+            case "major-change":
+                results.push(`Turn ${i}: ${base.split(" ").reverse().join(" ")}. Additional context: ${"y".repeat(200)}`);
+                break;
+        }
+    }
+    return results;
+}

package/dist/src/recall/async.js

@@ -0,0 +1,112 @@
+/**
+ * recall/async.ts — Slice 2 async cross-repo recall.
+ *
+ * Same dedup/bound/inline contract as `recallAndInline`, but backed by
+ * `VectorStore.searchAsync` so it can recall across repos (HNSW NN over the
+ * global PGlite index) when `opts.crossRepo` is set. The synchronous
+ * `recallAndInline` is unchanged and remains the default per-session path.
+ * Inline-window dedupe + token cap (Fix C) apply here too.
+ */
+import { vectorSearchAsync, vectorWasInjected, vectorMarkInjected, } from "../vectorStore.js";
+import { estimateBlockTokens } from "../tokens.js";
+import { defaultEmbedder, cosineSimilarity } from "../embedder.js";
+import { formatRecallBlock } from "./format.js";
+/**
+ * `store` must provide `searchAsync` (the live VectorStore does). Errors fall
+ * back to an empty result — recall is a bonus, never a hard dependency.
+ */
+export async function recallAndInlineAsync(opts, store) {
+    const limit = opts.limit ?? 3;
+    const skip = opts.skipInjected ?? true;
+    const maxTokens = opts.recallMaxTokens ?? 0;
+    const doWindowDedupe = opts.windowDedupe ?? false;
+    const dedupSim = opts.dedupSim ?? 0.9;
+    let hits = [];
+    try {
+        hits = await vectorSearchAsync(store, opts.sessionId, opts.query, limit, {
+            crossRepo: opts.crossRepo,
+            repoId: opts.repoId,
+        });
+    }
+    catch {
+        hits = [];
+    }
+    // F1: hoist one embedder instance for inline dedupe. defaultEmbedder() is
+    // deterministic but creating it per call wastes allocations on large hit sets.
+    // (recallAndInline already hoisted this; applying the same fix here.)
+    const embedder = defaultEmbedder();
+    let liveEmbeddings = [];
+    if (doWindowDedupe && opts.liveWindow && opts.liveWindow.length > 0) {
+        liveEmbeddings = opts.liveWindow.map((m) => embedder.embed(m));
+    }
+    const toInject = [];
+    let blockTokens = 0;
+    // F2: when cross-repo is on but no global index dir could be resolved, skip
+    // foreign hits rather than injecting them undeduped — otherwise a foreign
+    // checkpoint with no machine-wide injected-set to consult would re-inject in
+    // every new session. Same-repo hits (no repoId) are unaffected. Warn once so
+    // the silent degradation is observable. (The extension resolver normally
+    // supplies a default globalIndexDir, so this is belt-and-braces.)
+    const skipCrossRepoHits = !!opts.crossRepo && !opts.globalIndexDir;
+    if (skipCrossRepoHits) {
+        try {
+            console.warn("[mega-compact:recall] cross-repo recall enabled but globalIndexDir is unset — " +
+                "skipping cross-repo injection to avoid re-injecting undeduped foreign checkpoints");
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    for (const h of hits) {
+        // F2: skip foreign hits when we can't dedup them machine-wide.
+        if (skipCrossRepoHits && h.repoId)
+            continue;
+        if (skip &&
+            vectorWasInjected(store, opts.sessionId, h.checkpoint.checkpointId))
+            continue;
+        // S18: machine-wide injected-set — a foreign checkpoint already injected
+        // (in any session) is never re-injected. Only applies to cross-repo hits
+        // (same-repo hits have no repoId and are handled by the per-session set).
+        if (opts.globalIndexDir && h.repoId) {
+            try {
+                const { wasInjectedGlobal } = await import("./../store/sqlite.js");
+                if (wasInjectedGlobal(h.checkpoint.checkpointId, opts.sessionId, opts.globalIndexDir))
+                    continue;
+            }
+            catch {
+                /* non-fatal: degrade to per-session injected-set only */
+            }
+        }
+        // Inline dedupe: skip a hit already resident in the live window (F1: hoisted embedder).
+        if (doWindowDedupe && liveEmbeddings.length > 0) {
+            const hitVec = embedder.embed(h.checkpoint.summary);
+            if (liveEmbeddings.some((v) => cosineSimilarity(v, hitVec) >= dedupSim))
+                continue;
+        }
+        // F3: build the hit list first; format ONCE at the end so the block carries
+        // exactly one preamble and numbering [1..n] rather than one per hit.
+        const partTokens = estimateBlockTokens(h.checkpoint.summary);
+        if (maxTokens > 0 && blockTokens + partTokens > maxTokens)
+            break;
+        toInject.push(h);
+        blockTokens += partTokens;
+        vectorMarkInjected(store, opts.sessionId, h.checkpoint.checkpointId);
+        // S18: record the cross-repo injection machine-wide so it's not re-injected
+        // by a later recall (same or different session).
+        if (opts.globalIndexDir && h.repoId) {
+            try {
+                const { markInjectedGlobal } = await import("./../store/sqlite.js");
+                markInjectedGlobal(h.checkpoint.checkpointId, h.repoId, opts.sessionId, opts.globalIndexDir);
+            }
+            catch {
+                /* non-fatal */
+            }
+        }
+    }
+    // F3: format once — one preamble, correct [1..n] numbering, token cap counted
+    // against one preamble (not N). Pass the full toInject array so formatRecallBlock
+    // has repoId + score for proper labeling.
+    const block = toInject.length > 0 ? formatRecallBlock(toInject) : "";
+    const report = toInject.map((h) => `  • ${h.checkpoint.checkpointId} (${h.checkpoint.summary.slice(0, 60).replace(/\n/g, " ")}…)`);
+    return { toInject, report, block, empty: toInject.length === 0 };
+}

package/dist/src/recall/format.js

@@ -0,0 +1,149 @@
+import { rehydrateRaptorTree, isShadowMode } from "../dedup/raptor/index.js";
+import { maxCheckpointTimestamp } from "../store/sqlite.js";
+import { normalizeSessionId } from "../store.js";
+import { cosineSimilarity } from "../embedder.js";
+import { computeRecallMetrics } from "../recallMetrics.js";
+import { Logger } from "../log.js";
+/** Wrap a recall block so the model reads it as restored compacted context. */
+export function formatRecallBlock(hits) {
+    if (hits.length === 0)
+        return "";
+    const parts = hits.map((h, i) => {
+        const score = (h.score * 100).toFixed(0);
+        // S17: label a cross-repo hit with its source repo (the repoId doubles as
+        // that repo's stateDir, so the last path segment is the repo's display
+        // name). Same-repo hits (no repoId) stay unlabeled.
+        const repoName = h.repoId
+            ? ` (from repo ${h.repoId.split("/").filter(Boolean).pop() ?? h.repoId})`
+            : "";
+        // S42B: a RAPTOR cluster node hit (not a stored checkpoint) is labeled as a
+        // hierarchical summary and uses raptorSummary as its body. No Key files line
+        // (cluster nodes carry no file list).
+        if (h.raptorLevel !== undefined) {
+            return (`### Recalled cluster summary [${i + 1}] (level ${h.raptorLevel}, relevance ${score}%)${repoName}\n` +
+                `${(h.raptorSummary ?? h.checkpoint.summary).trim()}\n`);
+        }
+        return (`### Recalled context [${i + 1}] (relevance ${score}%)${repoName}\n` +
+            `${h.checkpoint.summary.trim()}\n` +
+            (h.checkpoint.filesModified.length
+                ? `Key files: ${h.checkpoint.filesModified.join(", ")}.\n`
+                : ""));
+    });
+    return ("The following compacted context was recalled from earlier in this session " +
+        "and is relevant to the current request. Treat it as background you already know:\n\n" +
+        parts.join("\n"));
+}
+/**
+ * S25 Phase-2: format the RAPTOR tree's top-level summary nodes (root + level-1
+ * clusters) as a hierarchical overview HEADER. Surfacing the high-level topical
+ * structure before the detailed checkpoint hits gives the model a map of what
+ * the session has covered. `nodes` are the RAPTOR summary nodes to surface,
+ * highest level first (root → level-1 clusters). Returns "" when empty.
+ */
+export function formatRaptorBlock(nodes) {
+    if (nodes.length === 0)
+        return "";
+    const parts = nodes.map((n, i) => {
+        const score = n.score !== undefined
+            ? ` (relevance ${(n.score * 100).toFixed(0)}%)`
+            : "";
+        const label = n.level === 0
+            ? `Session overview [${i + 1}]${score}`
+            : `Cluster summary [${i + 1}] (level ${n.level})${score}`;
+        return `### ${label}\n${n.summary.trim()}\n`;
+    });
+    return ("The following hierarchical overview summarizes the structure of this " +
+        "session so far. Use it as a map of what has been covered:\n\n" +
+        parts.join("\n"));
+}
+/** Format one memory hit for the recall block. Category + score for traceability. */
+export function formatMemoryRecallBlock(hits) {
+    if (hits.length === 0)
+        return "";
+    const parts = hits.map((h, i) => {
+        const pct = (h.score * 100).toFixed(0);
+        const cat = h.category ? `[${h.category}] ` : "";
+        const src = h.label ? ` ${h.label}` : "";
+        return `### Recalled memory [${i + 1}] (relevance ${pct}%${src})\n${cat}${h.content.trim()}`;
+    });
+    return ("The following facts about this project were saved from earlier turns " +
+        "and are relevant to the current request. Treat them as established:\n\n" +
+        parts.join("\n"));
+}
+/**
+ * S25 Phase-2: build the hierarchical overview header for a session. Rehydrates
+ * the persisted RAPTOR tree, picks the root + top level-1 cluster nodes by
+ * cosine similarity to the query, and formats them via formatRaptorBlock.
+ * Returns "" when no tree, stale tree, timedOut tree, or shadow mode. Non-fatal
+ * (wrapped in try/catch) — the overview is a bonus; a failure must never block
+ * the detailed recall block.
+ */
+export function raptorOverviewBlock(store, sessionId, query) {
+    try {
+        const sid = normalizeSessionId(sessionId);
+        // S25 gate: the overview header is part of the RAPTOR serve surface, so it
+        // must honor the same contract as raptorSearchHits — shadow mode is
+        // logging-only building, not injection.
+        if (isShadowMode())
+            return "";
+        const tree = rehydrateRaptorTree(sid, store.stateDir);
+        if (!tree || !tree.rootId || tree.timedOut)
+            return "";
+        // Freshness: a tree built before the session's latest checkpoint is stale.
+        const maxTs = maxCheckpointTimestamp(sid, store.stateDir);
+        if (tree.builtAt && tree.builtAt < maxTs)
+            return "";
+        const root = tree.nodes.get(tree.rootId);
+        if (!root)
+            return "";
+        const qv = store.embedder.embed(query);
+        // Root (level 0) first, then the top level-1 clusters by cosine to the query.
+        const nodes = [
+            {
+                summary: root.summary,
+                level: root.level,
+                score: cosineSimilarity(qv, root.embedding),
+            },
+        ];
+        const level1 = [...tree.nodes.values()]
+            .filter((n) => n.level === 1 && n.summary)
+            .map((n) => ({
+            summary: n.summary,
+            level: n.level,
+            score: cosineSimilarity(qv, n.embedding),
+        }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, 3);
+        nodes.push(...level1);
+        return formatRaptorBlock(nodes);
+    }
+    catch {
+        return ""; // non-fatal: overview is a bonus
+    }
+}
+/**
+ * B3: Compute recall-quality metrics on the injected hits and log them.
+ * Only called when RAG_RECALL_METRICS() is ON. Non-fatal.
+ */
+export function scoreAndLogRecallMetrics(query, toInject) {
+    try {
+        const logger = new Logger();
+        const metrics = computeRecallMetrics(query, toInject);
+        logger.info("recall_metrics", {
+            hitCount: toInject.length,
+            score: metrics.score,
+            pass: metrics.pass,
+        });
+        if (!metrics.pass && toInject.length > 0) {
+            logger.info("recall_metrics_low_quality", {
+                score: metrics.score,
+                relevance: metrics.breakdown.relevance,
+                coverage: metrics.breakdown.coverage,
+                diversity: metrics.breakdown.diversity,
+            });
+        }
+    }
+    catch {
+        /* non-fatal: metrics never break recall */
+    }
+}

package/dist/src/recall/memory.js

@@ -0,0 +1,62 @@
+/**
+ * recall/memory.ts — S21 memory recall: durables (decisions, rules,
+ * user-saved facts) live in the `memories` table. We mirror the checkpoint
+ * recall path: rank by cosine, format a block, respect a token cap so it can
+ * never net-inflate the system prompt.
+ */
+import { estimateBlockTokens } from "../tokens.js";
+import { formatMemoryRecallBlock } from "./format.js";
+/** Recall top-k durable memories, format into a token-capped block. */
+export async function recallMemoriesAndInline(opts) {
+    const limit = opts.limit ?? 5;
+    const maxTokens = opts.recallMaxTokens ?? 0;
+    const { recallMemories, recallMemoriesCrossRepo } = await import("../memoryRecall.js");
+    const hits = await recallMemories(opts.query, opts.stateDir, {
+        topK: limit,
+        minSimilarity: opts.minSimilarity ?? 0.2,
+    });
+    // S24 cross-repo augmentation: if same-repo recall is thin, pull additional
+    // memories from OTHER repos via the PGlite HNSW index. Non-fatal: a failure
+    // degrades to the same-repo hits only.
+    const crossHits = [];
+    if (opts.crossRepo && hits.length < limit) {
+        try {
+            const x = await recallMemoriesCrossRepo(opts.query, opts.stateDir, {
+                repo: null,
+                limit: limit - hits.length,
+                crossRepoCosine: opts.crossRepoCosine ?? 0.3,
+            });
+            for (const h of x)
+                crossHits.push(h);
+        }
+        catch {
+            /* non-fatal — cross-repo failure → same-repo only */
+        }
+    }
+    if (hits.length === 0 && crossHits.length === 0)
+        return { empty: true, block: "", report: [] };
+    // Same incremental token cap pattern as checkpoint recall.
+    const parts = [];
+    const report = [];
+    let blockTokens = 0;
+    const pushHit = (content, category, score, label, blockSuffix) => {
+        const part = formatMemoryRecallBlock([{ content, category, score, label: blockSuffix }]);
+        const partTokens = estimateBlockTokens(part);
+        if (maxTokens > 0 && blockTokens + partTokens > maxTokens)
+            return false;
+        parts.push(part);
+        report.push(`  • ${label} (${(score * 100).toFixed(0)}%): ${content.slice(0, 60).replace(/\n/g, " ")}…`);
+        blockTokens += partTokens;
+        return true;
+    };
+    for (const h of hits) {
+        if (!pushHit(h.memory.content, h.memory.category, h.score, `memory#${h.memory.id}`))
+            break;
+    }
+    for (const h of crossHits) {
+        const repoLabel = h.repoId.split(/[\\/]/).filter(Boolean).pop() ?? h.repoId;
+        if (!pushHit(h.memory.content, h.memory.category, h.score, `memory#${h.memory.id} (from ${repoLabel})`, `from ${repoLabel}`))
+            break;
+    }
+    return { empty: parts.length === 0, block: parts.join("\n"), report };
+}

package/dist/src/recall/reformulate.js

@@ -0,0 +1,82 @@
+/**
+ * recall/reformulate.ts — S57 RAG suite helpers (B1/B2).
+ *
+ * Each helper is only called when its feature flag (RAG_QUERY_REFORMULATION /
+ * RAG_TIERED_ROUTER) is ON; flag-OFF never reaches them. All degrade
+ * non-fatally to the standard path on any error.
+ */
+import { recall as searchRecall } from "../engine.js";
+import { defaultEmbedder } from "../embedder.js";
+import { reformulateQuery, isVagueQuery } from "../queryReformulation.js";
+import { VAGUE_MIN_WORDS, VAGUE_VERY_SHORT_WORDS } from "../queryReformulation/cache.js";
+import { getTieredRouter } from "../tieredRouter.js";
+/**
+ * B1: If the query is vague, reformulate it via embedding-neighbor TF-IDF
+ * expansion. Returns the original query when reformulation is not supported
+ * or the query is already specific. Non-fatal: any error → original query.
+ */
+export function reformulateRecallQuery(query, store, sessionId) {
+    try {
+        if (!isVagueQuery(query, {
+            vagueMinWords: VAGUE_MIN_WORDS,
+            vagueVeryShortWords: VAGUE_VERY_SHORT_WORDS,
+        }))
+            return query;
+        // Pre-compute neighbor candidates once. reformulateQuery embeds the query
+        // and calls `scan` internally; we return these pre-computed neighbors (same
+        // query) so the store needs no by-embedding lookup.
+        const { hits } = searchRecall({ sessionId, query, limit: 10, skipInjected: false }, store);
+        if (hits.length < 2)
+            return query; // too few neighbors for TF-IDF
+        const neighbors = hits.map((h) => ({
+            id: h.checkpoint.checkpointId,
+            score: h.score,
+        }));
+        const textById = new Map();
+        for (const h of hits)
+            textById.set(h.checkpoint.checkpointId, h.checkpoint.summary);
+        const scan = () => neighbors;
+        const corpus = {
+            totalDocs: neighbors.length,
+            docFreq: (term) => {
+                let df = 0;
+                for (const text of textById.values()) {
+                    if (text.toLowerCase().includes(term.toLowerCase()))
+                        df++;
+                }
+                return Math.max(df, 1);
+            },
+        };
+        const neighborTexts = (ids) => ids.map((id) => ({ id, text: textById.get(id) ?? "" }));
+        const { result } = reformulateQuery(query, defaultEmbedder(), scan, corpus, neighborTexts);
+        return result.expanded.length > query.length ? result.expanded : query;
+    }
+    catch {
+        return query; // non-fatal: fall back to original query
+    }
+}
+/**
+ * B2: Synchronous tiered recall. The TieredRouter.route() is async, so the
+ * sync path can only peek the L0 in-memory cache; on miss it falls through to
+ * the standard sync vector scan. The router's L1/L2 value is realized on the
+ * async path (recallAndInlineAsync). Non-fatal.
+ */
+export function runTieredRecall(query, sessionId, limit, skip, store) {
+    try {
+        const router = getTieredRouter();
+        if (!router) {
+            const result = searchRecall({ sessionId, query, limit, skipInjected: skip }, store);
+            return { newHits: result.newHits, tier: "off" };
+        }
+        // Peek the L0 in-memory cache synchronously; fall through on miss.
+        const cached = router.peekCache(sessionId, query, limit);
+        if (cached && cached.length > 0)
+            return { newHits: cached, tier: "L0-cache" };
+        const result = searchRecall({ sessionId, query, limit, skipInjected: skip }, store);
+        return { newHits: result.newHits, tier: "sync-fallback" };
+    }
+    catch {
+        const result = searchRecall({ sessionId, query, limit, skipInjected: skip }, store);
+        return { newHits: result.newHits, tier: "fallback-error" };
+    }
+}