@tobilu/qmd 1.0.7 → 1.1.2

package/dist/store.js

@@ -706,15 +706,24 @@ export function getDocid(hash) {
  * - Preserve folder structure (a/b/c/d.md stays structured)
  * - Preserve file extension
  */
+/** Replace emoji/symbol codepoints with their hex representation (e.g. 🐘 → 1f418) */
+function emojiToHex(str) {
+    return str.replace(/(?:\p{So}\p{Mn}?|\p{Sk})+/gu, (run) => {
+        // Split the run into individual emoji and convert each to hex, dash-separated
+        return [...run].filter(c => /\p{So}|\p{Sk}/u.test(c))
+            .map(c => c.codePointAt(0).toString(16)).join('-');
+    });
+}
 export function handelize(path) {
     if (!path || path.trim() === '') {
         throw new Error('handelize: path cannot be empty');
     }
     // Allow route-style "$" filenames while still rejecting paths with no usable content.
+    // Emoji (\p{So}) counts as valid content — they get converted to hex codepoints below.
     const segments = path.split('/').filter(Boolean);
     const lastSegment = segments[segments.length - 1] || '';
     const filenameWithoutExt = lastSegment.replace(/\.[^.]+$/, '');
-    const hasValidContent = /[\p{L}\p{N}$]/u.test(filenameWithoutExt);
+    const hasValidContent = /[\p{L}\p{N}\p{So}\p{Sk}$]/u.test(filenameWithoutExt);
     if (!hasValidContent) {
         throw new Error(`handelize: path "${path}" has no valid filename content`);
     }
@@ -724,6 +733,8 @@ export function handelize(path) {
         .split('/')
         .map((segment, idx, arr) => {
         const isLastSegment = idx === arr.length - 1;
+        // Convert emoji to hex codepoints before cleaning
+        segment = emojiToHex(segment);
         if (isLastSegment) {
             // For the filename (last segment), preserve the extension
             const extMatch = segment.match(/(\.[a-z0-9]+)$/i);
@@ -1510,15 +1521,108 @@ export function getTopLevelPathsWithoutContext(db, collectionName) {
 function sanitizeFTS5Term(term) {
     return term.replace(/[^\p{L}\p{N}']/gu, '').toLowerCase();
 }
+/**
+ * Parse lex query syntax into FTS5 query.
+ *
+ * Supports:
+ * - Quoted phrases: "exact phrase" → "exact phrase" (exact match)
+ * - Negation: -term or -"phrase" → uses FTS5 NOT operator
+ * - Plain terms: term → "term"* (prefix match)
+ *
+ * FTS5 NOT is a binary operator: `term1 NOT term2` means "match term1 but not term2".
+ * So `-term` only works when there are also positive terms.
+ *
+ * Examples:
+ *   performance -sports     → "performance"* NOT "sports"*
+ *   "machine learning"      → "machine learning"
+ */
 function buildFTS5Query(query) {
-    const terms = query.split(/\s+/)
-        .map(t => sanitizeFTS5Term(t))
-        .filter(t => t.length > 0);
-    if (terms.length === 0)
+    const positive = [];
+    const negative = [];
+    let i = 0;
+    const s = query.trim();
+    while (i < s.length) {
+        // Skip whitespace
+        while (i < s.length && /\s/.test(s[i]))
+            i++;
+        if (i >= s.length)
+            break;
+        // Check for negation prefix
+        const negated = s[i] === '-';
+        if (negated)
+            i++;
+        // Check for quoted phrase
+        if (s[i] === '"') {
+            const start = i + 1;
+            i++;
+            while (i < s.length && s[i] !== '"')
+                i++;
+            const phrase = s.slice(start, i).trim();
+            i++; // skip closing quote
+            if (phrase.length > 0) {
+                const sanitized = phrase.split(/\s+/).map(t => sanitizeFTS5Term(t)).filter(t => t).join(' ');
+                if (sanitized) {
+                    const ftsPhrase = `"${sanitized}"`; // Exact phrase, no prefix match
+                    if (negated) {
+                        negative.push(ftsPhrase);
+                    }
+                    else {
+                        positive.push(ftsPhrase);
+                    }
+                }
+            }
+        }
+        else {
+            // Plain term (until whitespace or quote)
+            const start = i;
+            while (i < s.length && !/[\s"]/.test(s[i]))
+                i++;
+            const term = s.slice(start, i);
+            const sanitized = sanitizeFTS5Term(term);
+            if (sanitized) {
+                const ftsTerm = `"${sanitized}"*`; // Prefix match
+                if (negated) {
+                    negative.push(ftsTerm);
+                }
+                else {
+                    positive.push(ftsTerm);
+                }
+            }
+        }
+    }
+    if (positive.length === 0 && negative.length === 0)
+        return null;
+    // If only negative terms, we can't search (FTS5 NOT is binary)
+    if (positive.length === 0)
         return null;
-    if (terms.length === 1)
-        return `"${terms[0]}"*`;
-    return terms.map(t => `"${t}"*`).join(' AND ');
+    // Join positive terms with AND
+    let result = positive.join(' AND ');
+    // Add NOT clause for negative terms
+    for (const neg of negative) {
+        result = `${result} NOT ${neg}`;
+    }
+    return result;
+}
+/**
+ * Validate that a vec/hyde query doesn't use lex-only syntax.
+ * Returns error message if invalid, null if valid.
+ */
+export function validateSemanticQuery(query) {
+    // Check for negation syntax
+    if (/-\w/.test(query) || /-"/.test(query)) {
+        return 'Negation (-term) is not supported in vec/hyde queries. Use lex for exclusions.';
+    }
+    return null;
+}
+export function validateLexQuery(query) {
+    if (/[\r\n]/.test(query)) {
+        return 'Lex queries must be a single line. Remove newline characters or split into separate lex: lines.';
+    }
+    const quoteCount = (query.match(/"/g) ?? []).length;
+    if (quoteCount % 2 === 1) {
+        return 'Lex query has an unmatched double quote ("). Add the closing quote or remove it.';
+    }
+    return null;
 }
 export function searchFTS(db, query, limit = 20, collectionName) {
     const ftsQuery = buildFTS5Query(query);
@@ -1652,7 +1756,7 @@ export async function searchVec(db, query, model, limit = 20, collectionName, se
 // =============================================================================
 async function getEmbedding(text, model, isQuery, session) {
     // Format text using the appropriate prompt template
-    const formattedText = isQuery ? formatQueryForEmbedding(text) : formatDocForEmbedding(text);
+    const formattedText = isQuery ? formatQueryForEmbedding(text, model) : formatDocForEmbedding(text, undefined, model);
     const result = session
         ? await session.embed(formattedText, { model, isQuery })
         : await getDefaultLlamaCpp().embed(formattedText, { model, isQuery });
@@ -1724,35 +1828,40 @@ export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db) {
 // =============================================================================
 export async function rerank(query, documents, model = DEFAULT_RERANK_MODEL, db) {
     const cachedResults = new Map();
-    const uncachedDocs = [];
+    const uncachedDocsByChunk = new Map();
     // Check cache for each document
     // Cache key includes chunk text — different queries can select different chunks
     // from the same file, and the reranker score depends on which chunk was sent.
+    // File path is excluded from the new cache key because the reranker score
+    // depends on the chunk content, not where it came from.
     for (const doc of documents) {
-        const cacheKey = getCacheKey("rerank", { query, file: doc.file, model, chunk: doc.text });
-        const cached = getCachedResult(db, cacheKey);
+        const cacheKey = getCacheKey("rerank", { query, model, chunk: doc.text });
+        const legacyCacheKey = getCacheKey("rerank", { query, file: doc.file, model, chunk: doc.text });
+        const cached = getCachedResult(db, cacheKey) ?? getCachedResult(db, legacyCacheKey);
         if (cached !== null) {
-            cachedResults.set(doc.file, parseFloat(cached));
+            cachedResults.set(doc.text, parseFloat(cached));
         }
         else {
-            uncachedDocs.push({ file: doc.file, text: doc.text });
+            uncachedDocsByChunk.set(doc.text, { file: doc.file, text: doc.text });
         }
     }
     // Rerank uncached documents using LlamaCpp
-    if (uncachedDocs.length > 0) {
+    if (uncachedDocsByChunk.size > 0) {
         const llm = getDefaultLlamaCpp();
+        const uncachedDocs = [...uncachedDocsByChunk.values()];
         const rerankResult = await llm.rerank(query, uncachedDocs, { model });
-        // Cache results — use original doc.text for cache key (result.file lacks chunk text)
-        const textByFile = new Map(documents.map(d => [d.file, d.text]));
+        // Cache results by chunk text so identical chunks across files are scored once.
+        const textByFile = new Map(uncachedDocs.map(d => [d.file, d.text]));
         for (const result of rerankResult.results) {
-            const cacheKey = getCacheKey("rerank", { query, file: result.file, model, chunk: textByFile.get(result.file) || "" });
+            const chunk = textByFile.get(result.file) || "";
+            const cacheKey = getCacheKey("rerank", { query, model, chunk });
             setCachedResult(db, cacheKey, result.score.toString());
-            cachedResults.set(result.file, result.score);
+            cachedResults.set(chunk, result.score);
         }
     }
     // Return all results sorted by score
     return documents
-        .map(doc => ({ file: doc.file, score: cachedResults.get(doc.file) || 0 }))
+        .map(doc => ({ file: doc.file, score: cachedResults.get(doc.text) || 0 }))
         .sort((a, b) => b.score - a.score);
 }
 // =============================================================================
@@ -1797,6 +1906,65 @@ export function reciprocalRankFusion(resultLists, weights = [], k = 60) {
         .sort((a, b) => b.rrfScore - a.rrfScore)
         .map(e => ({ ...e.result, score: e.rrfScore }));
 }
+/**
+ * Build per-document RRF contribution traces for explain/debug output.
+ */
+export function buildRrfTrace(resultLists, weights = [], listMeta = [], k = 60) {
+    const traces = new Map();
+    for (let listIdx = 0; listIdx < resultLists.length; listIdx++) {
+        const list = resultLists[listIdx];
+        if (!list)
+            continue;
+        const weight = weights[listIdx] ?? 1.0;
+        const meta = listMeta[listIdx] ?? {
+            source: "fts",
+            queryType: "original",
+            query: "",
+        };
+        for (let rank0 = 0; rank0 < list.length; rank0++) {
+            const result = list[rank0];
+            if (!result)
+                continue;
+            const rank = rank0 + 1; // 1-indexed rank for explain output
+            const contribution = weight / (k + rank);
+            const existing = traces.get(result.file);
+            const detail = {
+                listIndex: listIdx,
+                source: meta.source,
+                queryType: meta.queryType,
+                query: meta.query,
+                rank,
+                weight,
+                backendScore: result.score,
+                rrfContribution: contribution,
+            };
+            if (existing) {
+                existing.baseScore += contribution;
+                existing.topRank = Math.min(existing.topRank, rank);
+                existing.contributions.push(detail);
+            }
+            else {
+                traces.set(result.file, {
+                    contributions: [detail],
+                    baseScore: contribution,
+                    topRank: rank,
+                    topRankBonus: 0,
+                    totalScore: 0,
+                });
+            }
+        }
+    }
+    for (const trace of traces.values()) {
+        let bonus = 0;
+        if (trace.topRank === 1)
+            bonus = 0.05;
+        else if (trace.topRank <= 3)
+            bonus = 0.02;
+        trace.topRankBonus = bonus;
+        trace.totalScore = trace.baseScore + bonus;
+    }
+    return traces;
+}
 /**
  * Find a document by filename/path, docid (#hash), or with fuzzy matching.
  * Returns document metadata without body by default.
@@ -2171,8 +2339,10 @@ export async function hybridQuery(store, query, options) {
     const minScore = options?.minScore ?? 0;
     const candidateLimit = options?.candidateLimit ?? RERANK_CANDIDATE_LIMIT;
     const collection = options?.collection;
+    const explain = options?.explain ?? false;
     const hooks = options?.hooks;
     const rankedLists = [];
+    const rankedListMeta = [];
     const docidMap = new Map(); // filepath -> docid
     const hasVectors = !!store.db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
     // Step 1: BM25 probe — strong signal skips expensive LLM expansion
@@ -2186,10 +2356,12 @@ export async function hybridQuery(store, query, options) {
     if (hasStrongSignal)
         hooks?.onStrongSignal?.(topScore);
     // Step 2: Expand query (or skip if strong signal)
+    hooks?.onExpandStart?.();
+    const expandStart = Date.now();
     const expanded = hasStrongSignal
         ? []
         : await store.expandQuery(query);
-    hooks?.onExpand?.(query, expanded);
+    hooks?.onExpand?.(query, expanded, Date.now() - expandStart);
     // Seed with initial FTS results (avoid re-running original query FTS)
     if (initialFts.length > 0) {
         for (const r of initialFts)
@@ -2198,6 +2370,7 @@ export async function hybridQuery(store, query, options) {
             file: r.filepath, displayPath: r.displayPath,
             title: r.title, body: r.body || "", score: r.score,
         })));
+        rankedListMeta.push({ source: "fts", queryType: "original", query });
     }
     // Step 3: Route searches by query type
     //
@@ -2215,23 +2388,27 @@ export async function hybridQuery(store, query, options) {
                     file: r.filepath, displayPath: r.displayPath,
                     title: r.title, body: r.body || "", score: r.score,
                 })));
+                rankedListMeta.push({ source: "fts", queryType: "lex", query: q.text });
             }
         }
     }
     // 3b: Collect all texts that need vector search (original query + vec/hyde expansions)
     if (hasVectors) {
         const vecQueries = [
-            { text: query, isOriginal: true },
+            { text: query, queryType: "original" },
         ];
         for (const q of expanded) {
             if (q.type === 'vec' || q.type === 'hyde') {
-                vecQueries.push({ text: q.text, isOriginal: false });
+                vecQueries.push({ text: q.text, queryType: q.type });
             }
         }
         // Batch embed all vector queries in a single call
         const llm = getDefaultLlamaCpp();
         const textsToEmbed = vecQueries.map(q => formatQueryForEmbedding(q.text));
+        hooks?.onEmbedStart?.(textsToEmbed.length);
+        const embedStart = Date.now();
         const embeddings = await llm.embedBatch(textsToEmbed);
+        hooks?.onEmbedDone?.(Date.now() - embedStart);
         // Run sqlite-vec lookups with pre-computed embeddings
         for (let i = 0; i < vecQueries.length; i++) {
             const embedding = embeddings[i]?.embedding;
@@ -2245,12 +2422,18 @@ export async function hybridQuery(store, query, options) {
                     file: r.filepath, displayPath: r.displayPath,
                     title: r.title, body: r.body || "", score: r.score,
                 })));
+                rankedListMeta.push({
+                    source: "vec",
+                    queryType: vecQueries[i].queryType,
+                    query: vecQueries[i].text,
+                });
             }
         }
     }
     // Step 4: RRF fusion — first 2 lists (original FTS + first vec) get 2x weight
     const weights = rankedLists.map((_, i) => i < 2 ? 2.0 : 1.0);
     const fused = reciprocalRankFusion(rankedLists, weights);
+    const rrfTraceByFile = explain ? buildRrfTrace(rankedLists, weights, rankedListMeta) : null;
     const candidates = fused.slice(0, candidateLimit);
     if (candidates.length === 0)
         return [];
@@ -2279,8 +2462,9 @@ export async function hybridQuery(store, query, options) {
     }
     // Step 6: Rerank chunks (NOT full bodies)
     hooks?.onRerankStart?.(chunksToRerank.length);
+    const rerankStart = Date.now();
     const reranked = await store.rerank(query, chunksToRerank);
-    hooks?.onRerankDone?.();
+    hooks?.onRerankDone?.(Date.now() - rerankStart);
     // Step 7: Blend RRF position score with reranker score
     // Position-aware weights: top retrieval results get more protection from reranker disagreement
     const candidateMap = new Map(candidates.map(c => [c.file, {
@@ -2303,6 +2487,22 @@ export async function hybridQuery(store, query, options) {
         const bestIdx = chunkInfo?.bestIdx ?? 0;
         const bestChunk = chunkInfo?.chunks[bestIdx]?.text || candidate?.body || "";
         const bestChunkPos = chunkInfo?.chunks[bestIdx]?.pos || 0;
+        const trace = rrfTraceByFile?.get(r.file);
+        const explainData = explain ? {
+            ftsScores: trace?.contributions.filter(c => c.source === "fts").map(c => c.backendScore) ?? [],
+            vectorScores: trace?.contributions.filter(c => c.source === "vec").map(c => c.backendScore) ?? [],
+            rrf: {
+                rank: rrfRank,
+                positionScore: rrfScore,
+                weight: rrfWeight,
+                baseScore: trace?.baseScore ?? 0,
+                topRankBonus: trace?.topRankBonus ?? 0,
+                totalScore: trace?.totalScore ?? 0,
+                contributions: trace?.contributions ?? [],
+            },
+            rerankScore: r.score,
+            blendedScore,
+        } : undefined;
         return {
             file: r.file,
             displayPath: candidate?.displayPath || "",
@@ -2313,6 +2513,7 @@ export async function hybridQuery(store, query, options) {
             score: blendedScore,
             context: store.getContextForFile(r.file),
             docid: docidMap.get(r.file) || "",
+            ...(explainData ? { explain: explainData } : {}),
         };
     }).sort((a, b) => b.score - a.score);
     // Step 8: Dedup by file (safety net — prevents duplicate output)
@@ -2344,9 +2545,10 @@ export async function vectorSearchQuery(store, query, options) {
     if (!hasVectors)
         return [];
     // Expand query — filter to vec/hyde only (lex queries target FTS, not vector)
+    const expandStart = Date.now();
     const allExpanded = await store.expandQuery(query);
     const vecExpanded = allExpanded.filter(q => q.type !== 'lex');
-    options?.hooks?.onExpand?.(query, vecExpanded);
+    options?.hooks?.onExpand?.(query, vecExpanded, Date.now() - expandStart);
     // Run original + vec/hyde expanded through vector, sequentially — concurrent embed() hangs
     const queryTexts = [query, ...vecExpanded.map(q => q.text)];
     const allResults = new Map();
@@ -2372,3 +2574,212 @@ export async function vectorSearchQuery(store, query, options) {
         .filter(r => r.score >= minScore)
         .slice(0, limit);
 }
+/**
+ * Structured search: execute pre-expanded queries without LLM query expansion.
+ *
+ * Designed for LLM callers (MCP/HTTP) that generate their own query expansions.
+ * Skips the internal expandQuery() step — goes directly to:
+ *
+ * Pipeline:
+ * 1. Route searches: lex→FTS, vec/hyde→vector (batch embed)
+ * 2. RRF fusion across all result lists
+ * 3. Chunk documents + keyword-best-chunk selection
+ * 4. Rerank on chunks
+ * 5. Position-aware score blending
+ * 6. Dedup, filter, slice
+ *
+ * This is the recommended endpoint for capable LLMs — they can generate
+ * better query variations than our small local model, especially for
+ * domain-specific or nuanced queries.
+ */
+export async function structuredSearch(store, searches, options) {
+    const limit = options?.limit ?? 10;
+    const minScore = options?.minScore ?? 0;
+    const candidateLimit = options?.candidateLimit ?? RERANK_CANDIDATE_LIMIT;
+    const explain = options?.explain ?? false;
+    const hooks = options?.hooks;
+    const collections = options?.collections;
+    if (searches.length === 0)
+        return [];
+    // Validate queries before executing
+    for (const search of searches) {
+        const location = search.line ? `Line ${search.line}` : 'Structured search';
+        if (/[\r\n]/.test(search.query)) {
+            throw new Error(`${location} (${search.type}): queries must be single-line. Remove newline characters.`);
+        }
+        if (search.type === 'lex') {
+            const error = validateLexQuery(search.query);
+            if (error) {
+                throw new Error(`${location} (lex): ${error}`);
+            }
+        }
+        else if (search.type === 'vec' || search.type === 'hyde') {
+            const error = validateSemanticQuery(search.query);
+            if (error) {
+                throw new Error(`${location} (${search.type}): ${error}`);
+            }
+        }
+    }
+    const rankedLists = [];
+    const rankedListMeta = [];
+    const docidMap = new Map(); // filepath -> docid
+    const hasVectors = !!store.db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
+    // Helper to run search across collections (or all if undefined)
+    const collectionList = collections ?? [undefined]; // undefined = all collections
+    // Step 1: Run FTS for all lex searches (sync, instant)
+    for (const search of searches) {
+        if (search.type === 'lex') {
+            for (const coll of collectionList) {
+                const ftsResults = store.searchFTS(search.query, 20, coll);
+                if (ftsResults.length > 0) {
+                    for (const r of ftsResults)
+                        docidMap.set(r.filepath, r.docid);
+                    rankedLists.push(ftsResults.map(r => ({
+                        file: r.filepath, displayPath: r.displayPath,
+                        title: r.title, body: r.body || "", score: r.score,
+                    })));
+                    rankedListMeta.push({
+                        source: "fts",
+                        queryType: "lex",
+                        query: search.query,
+                    });
+                }
+            }
+        }
+    }
+    // Step 2: Batch embed and run vector searches for vec/hyde
+    if (hasVectors) {
+        const vecSearches = searches.filter((s) => s.type === 'vec' || s.type === 'hyde');
+        if (vecSearches.length > 0) {
+            const llm = getDefaultLlamaCpp();
+            const textsToEmbed = vecSearches.map(s => formatQueryForEmbedding(s.query));
+            hooks?.onEmbedStart?.(textsToEmbed.length);
+            const embedStart = Date.now();
+            const embeddings = await llm.embedBatch(textsToEmbed);
+            hooks?.onEmbedDone?.(Date.now() - embedStart);
+            for (let i = 0; i < vecSearches.length; i++) {
+                const embedding = embeddings[i]?.embedding;
+                if (!embedding)
+                    continue;
+                for (const coll of collectionList) {
+                    const vecResults = await store.searchVec(vecSearches[i].query, DEFAULT_EMBED_MODEL, 20, coll, undefined, embedding);
+                    if (vecResults.length > 0) {
+                        for (const r of vecResults)
+                            docidMap.set(r.filepath, r.docid);
+                        rankedLists.push(vecResults.map(r => ({
+                            file: r.filepath, displayPath: r.displayPath,
+                            title: r.title, body: r.body || "", score: r.score,
+                        })));
+                        rankedListMeta.push({
+                            source: "vec",
+                            queryType: vecSearches[i].type,
+                            query: vecSearches[i].query,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    if (rankedLists.length === 0)
+        return [];
+    // Step 3: RRF fusion — first list gets 2x weight (assume caller ordered by importance)
+    const weights = rankedLists.map((_, i) => i === 0 ? 2.0 : 1.0);
+    const fused = reciprocalRankFusion(rankedLists, weights);
+    const rrfTraceByFile = explain ? buildRrfTrace(rankedLists, weights, rankedListMeta) : null;
+    const candidates = fused.slice(0, candidateLimit);
+    if (candidates.length === 0)
+        return [];
+    hooks?.onExpand?.("", [], 0); // Signal no expansion (pre-expanded)
+    // Step 4: Chunk documents, pick best chunk per doc for reranking
+    // Use first lex query as the "query" for keyword matching, or first vec if no lex
+    const primaryQuery = searches.find(s => s.type === 'lex')?.query
+        || searches.find(s => s.type === 'vec')?.query
+        || searches[0]?.query || "";
+    const queryTerms = primaryQuery.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+    const chunksToRerank = [];
+    const docChunkMap = new Map();
+    for (const cand of candidates) {
+        const chunks = chunkDocument(cand.body);
+        if (chunks.length === 0)
+            continue;
+        // Pick chunk with most keyword overlap
+        let bestIdx = 0;
+        let bestScore = -1;
+        for (let i = 0; i < chunks.length; i++) {
+            const chunkLower = chunks[i].text.toLowerCase();
+            const score = queryTerms.reduce((acc, term) => acc + (chunkLower.includes(term) ? 1 : 0), 0);
+            if (score > bestScore) {
+                bestScore = score;
+                bestIdx = i;
+            }
+        }
+        chunksToRerank.push({ file: cand.file, text: chunks[bestIdx].text });
+        docChunkMap.set(cand.file, { chunks, bestIdx });
+    }
+    // Step 5: Rerank chunks
+    hooks?.onRerankStart?.(chunksToRerank.length);
+    const rerankStart2 = Date.now();
+    const reranked = await store.rerank(primaryQuery, chunksToRerank);
+    hooks?.onRerankDone?.(Date.now() - rerankStart2);
+    // Step 6: Blend RRF position score with reranker score
+    const candidateMap = new Map(candidates.map(c => [c.file, {
+            displayPath: c.displayPath, title: c.title, body: c.body,
+        }]));
+    const rrfRankMap = new Map(candidates.map((c, i) => [c.file, i + 1]));
+    const blended = reranked.map(r => {
+        const rrfRank = rrfRankMap.get(r.file) || candidateLimit;
+        let rrfWeight;
+        if (rrfRank <= 3)
+            rrfWeight = 0.75;
+        else if (rrfRank <= 10)
+            rrfWeight = 0.60;
+        else
+            rrfWeight = 0.40;
+        const rrfScore = 1 / rrfRank;
+        const blendedScore = rrfWeight * rrfScore + (1 - rrfWeight) * r.score;
+        const candidate = candidateMap.get(r.file);
+        const chunkInfo = docChunkMap.get(r.file);
+        const bestIdx = chunkInfo?.bestIdx ?? 0;
+        const bestChunk = chunkInfo?.chunks[bestIdx]?.text || candidate?.body || "";
+        const bestChunkPos = chunkInfo?.chunks[bestIdx]?.pos || 0;
+        const trace = rrfTraceByFile?.get(r.file);
+        const explainData = explain ? {
+            ftsScores: trace?.contributions.filter(c => c.source === "fts").map(c => c.backendScore) ?? [],
+            vectorScores: trace?.contributions.filter(c => c.source === "vec").map(c => c.backendScore) ?? [],
+            rrf: {
+                rank: rrfRank,
+                positionScore: rrfScore,
+                weight: rrfWeight,
+                baseScore: trace?.baseScore ?? 0,
+                topRankBonus: trace?.topRankBonus ?? 0,
+                totalScore: trace?.totalScore ?? 0,
+                contributions: trace?.contributions ?? [],
+            },
+            rerankScore: r.score,
+            blendedScore,
+        } : undefined;
+        return {
+            file: r.file,
+            displayPath: candidate?.displayPath || "",
+            title: candidate?.title || "",
+            body: candidate?.body || "",
+            bestChunk,
+            bestChunkPos,
+            score: blendedScore,
+            context: store.getContextForFile(r.file),
+            docid: docidMap.get(r.file) || "",
+            ...(explainData ? { explain: explainData } : {}),
+        };
+    }).sort((a, b) => b.score - a.score);
+    // Step 7: Dedup by file
+    const seenFiles = new Set();
+    return blended
+        .filter(r => {
+        if (seenFiles.has(r.file))
+            return false;
+        seenFiles.add(r.file);
+        return true;
+    })
+        .filter(r => r.score >= minScore)
+        .slice(0, limit);
+}

package/package.json

@@ -1,20 +1,19 @@
 {
   "name": "@tobilu/qmd",
-  "version": "1.0.7",
+  "version": "1.1.2",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
   "bin": {
-    "qmd": "qmd"
+    "qmd": "dist/qmd.js"
   },
   "files": [
     "dist/",
-    "qmd",
     "LICENSE",
     "CHANGELOG.md"
   ],
   "scripts": {
     "prepare": "[ -d .git ] && ./scripts/install-hooks.sh || true",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && printf '#!/usr/bin/env node\n' | cat - dist/qmd.js > dist/qmd.tmp && mv dist/qmd.tmp dist/qmd.js && chmod +x dist/qmd.js",
     "test": "vitest run --reporter=verbose test/",
     "qmd": "tsx src/qmd.ts",
     "index": "tsx src/qmd.ts index",
@@ -40,7 +39,7 @@
     "@modelcontextprotocol/sdk": "^1.25.1",
     "better-sqlite3": "^11.0.0",
     "fast-glob": "^3.3.0",
-    "node-llama-cpp": "^3.14.5",
+    "node-llama-cpp": "^3.17.1",
     "picomatch": "^4.0.0",
     "sqlite-vec": "^0.1.7-alpha.2",
     "yaml": "^2.8.2",
@@ -49,8 +48,9 @@
   "optionalDependencies": {
     "sqlite-vec-darwin-arm64": "^0.1.7-alpha.2",
     "sqlite-vec-darwin-x64": "^0.1.7-alpha.2",
+    "sqlite-vec-linux-arm64": "^0.1.7-alpha.2",
     "sqlite-vec-linux-x64": "^0.1.7-alpha.2",
-    "sqlite-vec-win32-x64": "^0.1.7-alpha.2"
+    "sqlite-vec-windows-x64": "^0.1.7-alpha.2"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",