ko-qmd 2.8.3-ko.8 → 2.8.3-ko.9

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+- Dependencies: `node-llama-cpp` 3.20.0 → **3.22.1**. ko-vault seam bench lines
+  are byte-identical before and after; Nix flake `qmd-node-modules` FOD hashes
+  refreshed for the new tree.
+
+## [2.8.3-ko.9] - 2026-10-10
+
+ko-qmd 2.8.3-ko.9 buys rank-1 accuracy and rerank latency at once. Per-document
+coverage weighting on relaxed lex lists takes hard `hybrid_r1` from 0.4444 to
+0.4778, and head-first rerank cascade halves rerank p50 with identical top-1
+answers. A load timeout (default 120 s) stops one stuck model load from hanging
+the query, as the scoring deadlines never covered the pre-ready wait.
+
+- `runWithDeadline` now bounds the model-load wait itself (`QMD_LLM_LOAD_TIMEOUT_MS`,
+  default 120 s, `0` = wait forever). The scoring deadlines never covered a load
+  that reports ready never: the pre-ready race hung with no timer, so one stuck
+  load hung the query. Past the load bound the stage is skipped exactly like a
+  scoring deadline (same `timeouts` entry, same RRF-order / original-query
+  fallback, same abandoned-run cache fill), and the bounded wait is reported as
+  the `load` stage. Listed in `qmd doctor`.
+- `QMD_RERANK_CASCADE=0` (or `false`/`off`/`no`) restores single-batch rerank.
+  Kill switch for measuring the cascade and for operations; unset cascades.
+  Listed in `qmd doctor`.
+- Rerank now cascades: the RRF head (15) is scored first, and the tail is
+  skipped with score 0 (RRF position order only) when the head's top-2 margin
+  reaches 0.08 (`RERANK_CASCADE_FIRST_BATCH`/`RERANK_CASCADE_MARGIN` in
+  `src/store.ts`). A contested top scores everything, as before; deadlines and
+  the rerank cache are unchanged (a skipped tail writes no cache entries).
+- `structuredSearch` and `hybridQuery` now weight a relaxed (any-word) lex list per
+  document by query coverage (`relaxedDocCoverage` in `src/store.ts`: 0.5 + 0.5 ×
+  matched units, mirroring the rerank chunk scorer's Hangul bigrams). A global
+  constant could not split the mirrored tie of `hmu-05` vs `sem-08` (2026-10-09
+  probe); both lead one list and take the same top-rank bonus, so only a per-doc
+  signal separates them. List weights are unchanged.
 ## [2.8.3-ko.8] - 2026-10-09
 
 - `structuredSearch` (MCP `searches`, SDK `search({ queries })`) no longer lets a relaxed

package/README.md

@@ -169,6 +169,8 @@ API 전체: [docs/REFERENCE.md § SDK / Library Usage](docs/REFERENCE.md#sdk--li
 |---|---|
 | `QMD_QUERY_LOG` | `1`/`true`/`yes` 면 HTTP 데몬이 검색마다 질의 로그를 남긴다 |
 | `QMD_LLM_IDLE_TIMEOUT_MS` | 모델을 내리기까지 idle ms (`0` = 내리지 않음) |
+| `QMD_LLM_LOAD_TIMEOUT_MS` | 모델 로드 대기의 상한 ms (기본 120000, `0` = 무한 대기). 넘으면 그 단계 없이 답하고 로드는 백그라운드에서 계속된다 |
+| `QMD_RERANK_CASCADE` | `0`/`false`/`off`/`no` 면 리랭크 cascade를 끄고 후보 전체를 한 번에 채점한다 |
 | `QMD_RERANK_MAX_DOC_TOKENS` | 리랭커에 보내는 문서당 토큰 cap (요청의 `rerankMaxDocTokens` 가 우선) |
 | `QMD_RERANK_CONTEXT_SIZE` · `QMD_EMBED_CONTEXT_SIZE` · `QMD_EXPAND_CONTEXT_SIZE` | 역할별 context 크기 |
 | `QMD_EMBED_PARALLELISM` | 병렬 context 수 (높으면 RAM/VRAM 고갈) |

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "6698cd5",
-  "builtAt": "2026-10-09T05:15:35.019Z"
+  "commit": "ba437e0",
+  "builtAt": "2026-10-10T08:52:03.340Z"
 }

package/dist/cli/qmd.js

@@ -3583,6 +3583,8 @@ function collectEnvironmentOverrides(activeModels, configModels = {}) {
     add("QMD_DOCTOR_DEVICE_PROBE", "controls qmd doctor native device probing; 0/off skips GPU probing");
     add("QMD_EMBED_PARALLELISM", "overrides embedding parallel context count; too high can exhaust RAM/VRAM");
     add("QMD_LLM_IDLE_TIMEOUT_MS", "ms of idle before models unload (0 = never); keeping them loaded holds their memory");
+    add("QMD_LLM_LOAD_TIMEOUT_MS", "caps the model-load wait per stage (default 120000, 0 = wait forever); past it the stage is skipped");
+    add("QMD_RERANK_CASCADE", "0/false/off/no disables head-first cascade rerank and scores all candidates at once");
     add("QMD_EXPAND_CONTEXT_SIZE", "overrides query expansion context size; larger values use more memory");
     add("QMD_RERANK_CONTEXT_SIZE", "overrides reranker context size; larger values use more memory");
     add("QMD_RERANK_MAX_DOC_TOKENS", "caps tokens per document sent to the reranker; lower is faster but scores less text");

package/dist/mcp/server.js

@@ -128,6 +128,9 @@ function stageTimer() {
  * ko-qmd: how long the daemon waits for query expansion and for the reranker before answering
  * without them. QMD_EXPAND_DEADLINE_MS / QMD_RERANK_DEADLINE_MS: 0 = wait, a positive integer =
  * that many ms, anything else = the default. One MCP query once took 85 s.
+ * The model-load wait itself is bounded separately by QMD_LLM_LOAD_TIMEOUT_MS
+ * (default 120 s, 0 = wait forever), so a load that never reports ready also
+ * falls back instead of hanging.
  */
 const DEFAULT_EXPAND_DEADLINE_MS = 5_000;
 const DEFAULT_RERANK_DEADLINE_MS = 10_000;

package/dist/store.d.ts

@@ -477,6 +477,7 @@ export type RRFContributionTrace = {
     query: string;
     rank: number;
     weight: number;
+    multiplier?: number;
     backendScore: number;
     rrfContribution: number;
 };
@@ -912,11 +913,32 @@ export declare function rerank(query: string, documents: {
     file: string;
     score: number;
 }[]>;
-export declare function reciprocalRankFusion(resultLists: RankedResult[][], weights?: number[], k?: number): RankedResult[];
+/**
+ * Fraction of the query's units present in the document body, used to weight a
+ * relaxed (any-word) FTS list per document instead of one global constant
+ * (BASELINE.md 2026-10-09 follow-up: a global weight cannot split the mirrored
+ * tie of `hmu-05` vs `sem-08`).
+ *
+ * Units mirror the rerank chunk scorer: one per Hangul run of two or more
+ * syllables (a run of three or more also matches on any shared syllable
+ * bigram, so a particle-suffixed word meets its stem), one per Latin/digit run
+ * longer than two characters. Single syllables and short tokens carry no
+ * signal and are skipped. A query with no units covers everything (1.0) so it
+ * never punishes.
+ */
+export declare function relaxedDocCoverage(query: string, body: string): number;
+/**
+ * Per-document RRF multipliers, aligned with `rankedLists`: a relaxed list
+ * scales each document by `0.5 + 0.5 × coverage`, every other list is untouched
+ * (`undefined` entry = multiplier 1.0). The 0.5 floor keeps a zero-coverage
+ * candidate in the pool instead of erasing it.
+ */
+export declare function rrfDocMultipliers(rankedLists: RankedResult[][], rankedListMeta: RankedListMeta[]): Array<Map<string, number> | undefined>;
+export declare function reciprocalRankFusion(resultLists: RankedResult[][], weights?: number[], k?: number, docMultipliers?: Array<Map<string, number> | undefined>): RankedResult[];
 /**
  * Build per-document RRF contribution traces for explain/debug output.
  */
-export declare function buildRrfTrace(resultLists: RankedResult[][], weights?: number[], listMeta?: RankedListMeta[], k?: number): Map<string, RRFScoreTrace>;
+export declare function buildRrfTrace(resultLists: RankedResult[][], weights?: number[], listMeta?: RankedListMeta[], k?: number, docMultipliers?: Array<Map<string, number> | undefined>): Map<string, RRFScoreTrace>;
 /**
  * Find a document by filename/path, docid (#hash), or with fuzzy matching.
  * Returns document metadata without body by default.
@@ -1104,6 +1126,41 @@ export declare function getStructuredRrfWeights(rankedListMeta: RankedListMeta[]
  */
 export declare function blendRerankScore(rrfRank: number, rerankScore: number, candidateLimit: number): number;
 export type DeadlineStage = "expand" | "rerank";
+/**
+ * Bound on the model-load wait inside runWithDeadline: a load that never
+ * reports ready must not hang the query. QMD_LLM_LOAD_TIMEOUT_MS sets it
+ * (positive ms, 0 = wait forever, anything else = the default).
+ */
+export declare const DEFAULT_LOAD_TIMEOUT_MS = 120000;
+/** Load-timeout resolver for runWithDeadline; exported for tests. */
+export declare function resolveLoadTimeoutMs(): number;
+/** Rerank `chunks`, or null when the reranker misses `deadlineMs` (the caller then answers in RRF order). */
+export declare const RERANK_CASCADE_FIRST_BATCH = 15;
+/** Skip the tail past the first batch when the top-2 rerank margin reaches this. */
+export declare const RERANK_CASCADE_MARGIN = 0.08;
+/**
+ * QMD_RERANK_CASCADE=0 (or false/off/no) restores single-batch rerank;
+ * anything else (including unset) cascades. Kill switch for measurement and
+ * operations; exported for tests.
+ */
+export declare function isRerankCascadeEnabled(): boolean;
+/**
+ * True when the first cascade batch's top-2 margin is too tight to skip the
+ * tail: a contested top means an unscored document could still win the blend.
+ * A batch of fewer than two holds nothing to contest.
+ */
+export declare function cascadeNeedsSecondBatch(sortedScores: number[], margin?: number): boolean;
+export declare function rerankWithDeadline(store: Store, query: string, chunks: {
+    file: string;
+    text: string;
+}[], intent: string | undefined, options: {
+    rerankMaxDocTokens?: number;
+    rerankDeadlineMs?: number;
+    hooks?: SearchHooks;
+} | undefined): Promise<{
+    file: string;
+    score: number;
+}[] | null>;
 /**
  * Hybrid search: BM25 + vector + query expansion + RRF + chunked reranking.
  *

package/dist/store.js

@@ -3889,18 +3889,88 @@ export async function rerank(query, documents, model = DEFAULT_RERANK_MODEL, db,
 // =============================================================================
 // Reciprocal Rank Fusion
 // =============================================================================
-export function reciprocalRankFusion(resultLists, weights = [], k = 60) {
+const COVERAGE_HANGUL_RUN_PATTERN = /\p{Script=Hangul}+/gu;
+const COVERAGE_LATIN_RUN_PATTERN = /[a-z0-9]+/gi;
+/**
+ * Fraction of the query's units present in the document body, used to weight a
+ * relaxed (any-word) FTS list per document instead of one global constant
+ * (BASELINE.md 2026-10-09 follow-up: a global weight cannot split the mirrored
+ * tie of `hmu-05` vs `sem-08`).
+ *
+ * Units mirror the rerank chunk scorer: one per Hangul run of two or more
+ * syllables (a run of three or more also matches on any shared syllable
+ * bigram, so a particle-suffixed word meets its stem), one per Latin/digit run
+ * longer than two characters. Single syllables and short tokens carry no
+ * signal and are skipped. A query with no units covers everything (1.0) so it
+ * never punishes.
+ */
+export function relaxedDocCoverage(query, body) {
+    const lower = body.toLowerCase();
+    let total = 0;
+    let matched = 0;
+    for (const token of query.toLowerCase().split(/\s+/)) {
+        if (!token)
+            continue;
+        for (const run of token.match(COVERAGE_HANGUL_RUN_PATTERN) ?? []) {
+            const syllables = Array.from(run);
+            if (syllables.length < 2)
+                continue;
+            total++;
+            if (lower.includes(run)) {
+                matched++;
+                continue;
+            }
+            if (syllables.length >= 3) {
+                for (let i = 0; i + 1 < syllables.length; i++) {
+                    if (lower.includes(syllables[i] + syllables[i + 1])) {
+                        matched++;
+                        break;
+                    }
+                }
+            }
+        }
+        for (const run of token.match(COVERAGE_LATIN_RUN_PATTERN) ?? []) {
+            if (run.length <= 2)
+                continue;
+            total++;
+            if (lower.includes(run))
+                matched++;
+        }
+    }
+    return total === 0 ? 1 : matched / total;
+}
+/**
+ * Per-document RRF multipliers, aligned with `rankedLists`: a relaxed list
+ * scales each document by `0.5 + 0.5 × coverage`, every other list is untouched
+ * (`undefined` entry = multiplier 1.0). The 0.5 floor keeps a zero-coverage
+ * candidate in the pool instead of erasing it.
+ */
+export function rrfDocMultipliers(rankedLists, rankedListMeta) {
+    return rankedLists.map((list, i) => {
+        const meta = rankedListMeta[i];
+        if (!meta?.relaxed)
+            return undefined;
+        const multipliers = new Map();
+        for (const r of list) {
+            multipliers.set(r.file, 0.5 + 0.5 * relaxedDocCoverage(meta.query, r.body));
+        }
+        return multipliers;
+    });
+}
+export function reciprocalRankFusion(resultLists, weights = [], k = 60, docMultipliers = []) {
     const scores = new Map();
     for (let listIdx = 0; listIdx < resultLists.length; listIdx++) {
         const list = resultLists[listIdx];
         if (!list)
             continue;
         const weight = weights[listIdx] ?? 1.0;
+        const multipliers = docMultipliers[listIdx];
         for (let rank = 0; rank < list.length; rank++) {
             const result = list[rank];
             if (!result)
                 continue;
-            const rrfContribution = weight / (k + rank + 1);
+            const multiplier = multipliers?.get(result.file) ?? 1.0;
+            const rrfContribution = (weight * multiplier) / (k + rank + 1);
             const existing = scores.get(result.file);
             if (existing) {
                 existing.rrfScore += rrfContribution;
@@ -3931,13 +4001,14 @@ export function reciprocalRankFusion(resultLists, weights = [], k = 60) {
 /**
  * Build per-document RRF contribution traces for explain/debug output.
  */
-export function buildRrfTrace(resultLists, weights = [], listMeta = [], k = 60) {
+export function buildRrfTrace(resultLists, weights = [], listMeta = [], k = 60, docMultipliers = []) {
     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 multipliers = docMultipliers[listIdx];
         const meta = listMeta[listIdx] ?? {
             source: "fts",
             queryType: "original",
@@ -3948,7 +4019,8 @@ export function buildRrfTrace(resultLists, weights = [], listMeta = [], k = 60)
             if (!result)
                 continue;
             const rank = rank0 + 1; // 1-indexed rank for explain output
-            const contribution = weight / (k + rank);
+            const multiplier = multipliers?.get(result.file) ?? 1.0;
+            const contribution = (weight * multiplier) / (k + rank);
             const existing = traces.get(result.file);
             const detail = {
                 listIndex: listIdx,
@@ -3957,6 +4029,7 @@ export function buildRrfTrace(resultLists, weights = [], listMeta = [], k = 60)
                 query: meta.query,
                 rank,
                 weight,
+                multiplier,
                 backendScore: result.score,
                 rrfContribution: contribution,
             };
@@ -4667,26 +4740,45 @@ async function withDeadline(promise, deadlineMs) {
  * skipped instead: this caps the backlog at one abandoned call per stage instead of one per query.
  */
 const abandoned = new WeakMap();
+/**
+ * Bound on the model-load wait inside runWithDeadline: a load that never
+ * reports ready must not hang the query. QMD_LLM_LOAD_TIMEOUT_MS sets it
+ * (positive ms, 0 = wait forever, anything else = the default).
+ */
+export const DEFAULT_LOAD_TIMEOUT_MS = 120_000;
+/** Load-timeout resolver for runWithDeadline; exported for tests. */
+export function resolveLoadTimeoutMs() {
+    const raw = process.env.QMD_LLM_LOAD_TIMEOUT_MS?.trim();
+    if (raw === undefined || raw === "")
+        return DEFAULT_LOAD_TIMEOUT_MS;
+    return /^\d+$/.test(raw) ? Number(raw) : DEFAULT_LOAD_TIMEOUT_MS;
+}
 /**
  * Run one LLM stage under a deadline. The clock starts once the stage's model is loaded
  * (`onModelReady`): the deadline bounds computation, not a cold load, which is reported through
- * `onModelLoad`. TIMED_OUT when the deadline passes, or at once while an earlier abandoned call of
- * the stage is still running. Unset or 0 deadline = plain await.
+ * `onModelLoad`. The load wait itself is bounded separately by resolveLoadTimeoutMs, so a load
+ * that never reports ready times out instead of hanging. TIMED_OUT when either bound passes,
+ * or at once while an earlier abandoned call of the stage is still running.
+ * Unset or 0 deadline = plain await (still under the load bound).
  */
 async function runWithDeadline(store, stage, deadlineMs, hooks, start) {
     const started = Date.now();
     let loadedAt;
     const reportLoad = () => { if (loadedAt !== undefined)
         hooks?.onModelLoad?.(stage, loadedAt - started); };
-    if (!deadlineMs || deadlineMs <= 0) {
-        const value = await start(() => { loadedAt = Date.now(); });
-        reportLoad();
-        return value;
-    }
     const byStage = abandoned.get(store) ?? { expand: { running: 0, warned: false }, rerank: { running: 0, warned: false } };
     abandoned.set(store, byStage);
     const state = byStage[stage];
-    if (state.running > 0) {
+    const abandon = () => {
+        state.running++;
+        const settle = () => {
+            state.running--;
+            if (state.running === 0)
+                state.warned = false;
+        };
+        pending.then(settle, settle);
+    };
+    if (deadlineMs && deadlineMs > 0 && state.running > 0) {
         if (!state.warned) {
             state.warned = true;
             process.stderr.write(`qmd: a ${stage} abandoned at its deadline is still running — answering without ${stage} until it finishes\n`);
@@ -4697,30 +4789,101 @@ async function runWithDeadline(store, stage, deadlineMs, hooks, start) {
     let markReady = () => { };
     const ready = new Promise((resolve) => { markReady = () => { loadedAt = Date.now(); resolve(); }; });
     const pending = start(markReady);
-    // Wait out the model load with no deadline; a cache hit or a fast call may finish before it fires.
-    const finishedFirst = await Promise.race([ready.then(() => false), pending.then(() => true, () => true)]);
+    // Bound the load wait itself: neither a stuck load nor a call that finishes
+    // without reporting ready may hold the query past the load timeout. The
+    // timer is cleared on every settle so idle processes keep no handle.
+    const loadTimeoutMs = resolveLoadTimeoutMs();
+    let loadTimer;
+    const loadTimedOut = new Promise((resolve) => {
+        if (loadTimeoutMs > 0) {
+            loadTimer = setTimeout(() => resolve("load-timeout"), loadTimeoutMs);
+            loadTimer.unref?.();
+        }
+    });
+    const settled = await Promise.race([
+        ready.then(() => "ready"),
+        loadTimedOut,
+        pending.then(() => "done", () => "done"),
+    ]);
+    clearTimeout(loadTimer);
+    if (settled === "load-timeout") {
+        abandon();
+        hooks?.onModelLoad?.(stage, Date.now() - started);
+        hooks?.onDeadline?.(stage, Date.now() - started);
+        return TIMED_OUT;
+    }
     reportLoad();
-    if (finishedFirst)
+    if (settled === "done")
+        return pending;
+    if (!deadlineMs || deadlineMs <= 0)
         return pending;
     const result = await withDeadline(pending, deadlineMs);
     if (result === TIMED_OUT) {
-        state.running++;
-        const settle = () => {
-            state.running--;
-            if (state.running === 0)
-                state.warned = false;
-        };
-        pending.then(settle, settle);
+        abandon();
         hooks?.onDeadline?.(stage, Date.now() - (loadedAt ?? started));
     }
     return result;
 }
 /** Rerank `chunks`, or null when the reranker misses `deadlineMs` (the caller then answers in RRF order). */
-async function rerankWithDeadline(store, query, chunks, intent, options) {
+export const RERANK_CASCADE_FIRST_BATCH = 15;
+/** Skip the tail past the first batch when the top-2 rerank margin reaches this. */
+export const RERANK_CASCADE_MARGIN = 0.08;
+/**
+ * QMD_RERANK_CASCADE=0 (or false/off/no) restores single-batch rerank;
+ * anything else (including unset) cascades. Kill switch for measurement and
+ * operations; exported for tests.
+ */
+export function isRerankCascadeEnabled() {
+    const raw = process.env.QMD_RERANK_CASCADE?.trim().toLowerCase();
+    return raw !== "0" && raw !== "false" && raw !== "off" && raw !== "no";
+}
+/**
+ * True when the first cascade batch's top-2 margin is too tight to skip the
+ * tail: a contested top means an unscored document could still win the blend.
+ * A batch of fewer than two holds nothing to contest.
+ */
+export function cascadeNeedsSecondBatch(sortedScores, margin = RERANK_CASCADE_MARGIN) {
+    if (sortedScores.length < 2)
+        return false;
+    const [top, second] = [sortedScores[0], sortedScores[1]];
+    if (!Number.isFinite(top) || !Number.isFinite(second))
+        return true;
+    return top - second < margin;
+}
+export async function rerankWithDeadline(store, query, chunks, intent, options) {
     const hooks = options?.hooks;
     hooks?.onRerankStart?.(chunks.length);
     const start = Date.now();
-    const reranked = await runWithDeadline(store, "rerank", options?.rerankDeadlineMs, hooks, (onModelReady) => store.rerank(query, chunks, undefined, intent, { maxDocTokens: options?.rerankMaxDocTokens, onModelReady }));
+    const scoreBatch = (docs, deadlineMs) => runWithDeadline(store, "rerank", deadlineMs, hooks, (onModelReady) => store.rerank(query, docs, undefined, intent, { maxDocTokens: options?.rerankMaxDocTokens, onModelReady }));
+    // Cascade: score the RRF head first. On a decisive top margin the tail keeps
+    // score 0 (RRF position tiebreak only) instead of paying for 25 more
+    // cross-encoder pairs; a contested top scores everything, as before.
+    if (isRerankCascadeEnabled() && chunks.length > RERANK_CASCADE_FIRST_BATCH) {
+        const first = chunks.slice(0, RERANK_CASCADE_FIRST_BATCH);
+        const rest = chunks.slice(RERANK_CASCADE_FIRST_BATCH);
+        const firstScored = await scoreBatch(first, options?.rerankDeadlineMs);
+        if (firstScored === TIMED_OUT)
+            return null;
+        const headroom = [...firstScored].sort((a, b) => b.score - a.score).map((r) => r.score);
+        if (!cascadeNeedsSecondBatch(headroom)) {
+            hooks?.onRerankDone?.(Date.now() - start);
+            return [...firstScored, ...rest.map((d) => ({ file: d.file, score: 0 }))];
+        }
+        // The second batch shares the caller's deadline: it gets only the remaining
+        // budget, so the worst case stays one deadline, not two. An exhausted budget
+        // is the same as a timeout — the caller falls back to RRF order.
+        // Same "no deadline" rule as runWithDeadline: unset or <= 0 waits unbounded.
+        const deadlineMs = options?.rerankDeadlineMs;
+        const remaining = deadlineMs && deadlineMs > 0 ? deadlineMs - (Date.now() - start) : undefined;
+        if (remaining !== undefined && remaining <= 0)
+            return null;
+        const restScored = await scoreBatch(rest, remaining);
+        if (restScored === TIMED_OUT)
+            return null;
+        hooks?.onRerankDone?.(Date.now() - start);
+        return [...firstScored, ...restScored];
+    }
+    const reranked = await scoreBatch(chunks, options?.rerankDeadlineMs);
     if (reranked === TIMED_OUT)
         return null;
     hooks?.onRerankDone?.(Date.now() - start);
@@ -4906,9 +5069,11 @@ export async function hybridQuery(store, rawQuery, options) {
     }
     // Step 4: RRF fusion — original-query FTS and vector lists get 2x weight;
     // expansion-derived lists stay at 1x independent of insertion order.
+    // A relaxed list additionally scales each document by its query coverage.
     const weights = getHybridRrfWeights(rankedListMeta);
-    const fused = reciprocalRankFusion(rankedLists, weights);
-    const rrfTraceByFile = explain ? buildRrfTrace(rankedLists, weights, rankedListMeta) : null;
+    const docMultipliers = rrfDocMultipliers(rankedLists, rankedListMeta);
+    const fused = reciprocalRankFusion(rankedLists, weights, 60, docMultipliers);
+    const rrfTraceByFile = explain ? buildRrfTrace(rankedLists, weights, rankedListMeta, 60, docMultipliers) : null;
     const candidates = fused.slice(0, candidateLimit);
     if (candidates.length === 0)
         return [];
@@ -5204,10 +5369,11 @@ export async function structuredSearch(store, rawSearches, options) {
     if (rankedLists.length === 0)
         return [];
     // Step 3: RRF fusion — first list gets 2x weight (assume caller ordered by importance),
-    // a relaxed FTS list half of its slot's weight
+    // a relaxed FTS list half of its slot's weight, scaled per document by query coverage
     const weights = getStructuredRrfWeights(rankedListMeta);
-    const fused = reciprocalRankFusion(rankedLists, weights);
-    const rrfTraceByFile = explain ? buildRrfTrace(rankedLists, weights, rankedListMeta) : null;
+    const docMultipliers = rrfDocMultipliers(rankedLists, rankedListMeta);
+    const fused = reciprocalRankFusion(rankedLists, weights, 60, docMultipliers);
+    const rrfTraceByFile = explain ? buildRrfTrace(rankedLists, weights, rankedListMeta, 60, docMultipliers) : null;
     const candidates = fused.slice(0, candidateLimit);
     if (candidates.length === 0)
         return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ko-qmd",
-  "version": "2.8.3-ko.8",
+  "version": "2.8.3-ko.9",
   "description": "Local hybrid search for Korean Markdown notes and Obsidian vaults — BM25 with Korean particle stripping, Hangul bigram FTS, Qwen3 vector search and LLM reranking, as CLI, MCP server and SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -60,7 +60,7 @@
     "@modelcontextprotocol/server": "2.0.0",
     "better-sqlite3": "^13.0.3",
     "fast-glob": "3.3.3",
-    "node-llama-cpp": "3.20.0",
+    "node-llama-cpp": "3.22.1",
     "picomatch": "4.0.5",
     "sqlite-vec": "0.1.9",
     "tree-sitter-go": "0.25.0",