md-semantic-search 1.1.0 → 2.0.0

package/dist/lexical.js

@@ -100,6 +100,90 @@ export function editDistance(a, b) {
     }
     return matrix[alen][blen];
 }
+/**
+ * Damerau-Levenshtein distance with a threshold (issue #193): banded DP that
+ * never leaves the |i-j| <= maxDist diagonal and aborts as soon as the whole
+ * row exceeds the threshold — O(maxDist × min(alen, blen)) instead of the
+ * full O(alen × blen) matrix. Returns the EXACT distance when it is
+ * <= maxDist and null otherwise; decisions are identical to
+ * `editDistance(a, b) <= maxDist` (optimal paths within the threshold never
+ * leave the band).
+ */
+export function editDistanceAtMost(a, b, maxDist) {
+    if (a === b)
+        return 0;
+    const alen = a.length;
+    const blen = b.length;
+    if (Math.abs(alen - blen) > maxDist)
+        return null;
+    if (alen === 0)
+        return blen <= maxDist ? blen : null;
+    if (blen === 0)
+        return alen <= maxDist ? alen : null;
+    if (maxDist < 0)
+        return null;
+    const INF = maxDist + 1;
+    // rows are padded with an INF sentinel column on each side so band-edge
+    // lookups (j-1 / j+1) never read a real out-of-band value
+    const width = blen + 3;
+    const rowA = new Int32Array(width);
+    const rowB = new Int32Array(width);
+    const rowC = new Int32Array(width);
+    let prev2 = null; // row i-2 (for transpositions)
+    let prev = rowA;
+    let cur = rowB;
+    const scratch = rowC;
+    for (let j = 1; j <= blen + 1; j++)
+        prev[j] = j; // row 0: dp[0][j] = j (col 0 unused sentinel)
+    prev[0] = 0;
+    for (let i = 1; i <= alen; i++) {
+        const jLo = Math.max(1, i - maxDist);
+        const jHi = Math.min(blen, i + maxDist);
+        cur[0] = i; // dp[i][0] = i (column 0 inside the band only when i <= maxDist)
+        if (i > maxDist)
+            cur[0] = INF;
+        let rowMin = cur[0];
+        for (let j = jLo; j <= jHi; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            let v = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1] && prev2 !== null) {
+                v = Math.min(v, prev2[j - 2] + cost);
+            }
+            cur[j] = v;
+            if (v < rowMin)
+                rowMin = v;
+        }
+        // band-out cells stay INF for this row
+        for (let j = 1; j <= blen; j++) {
+            if (j < jLo || j > jHi)
+                cur[j] = INF;
+        }
+        if (rowMin > maxDist)
+            return null;
+        // three-row rotation: prev2 <- row(i-1), prev <- row(i), cur <- freed row
+        const free = prev2 ?? scratch;
+        prev2 = prev;
+        prev = cur;
+        cur = free;
+    }
+    const d = prev[blen];
+    return d <= maxDist ? d : null;
+}
+/**
+ * issue #193: target tokenization memoized per chunk object — the fuzzy scan
+ * runs on every query, but a chunk's title/aliases tokenize to the same tokens
+ * every time. WeakMap so runtime chunks (stable objects in serve) pay once.
+ */
+const fuzzyTargetTokens = new WeakMap();
+function targetTokens(chunk) {
+    let tokens = fuzzyTargetTokens.get(chunk);
+    if (!tokens) {
+        const targets = [chunk.title, ...(chunk.meta?.aliases || [])].filter(Boolean);
+        tokens = targets.flatMap((t) => tokenize(t));
+        fuzzyTargetTokens.set(chunk, tokens);
+    }
+    return tokens;
+}
 export function fuzzyTitleAliasScores(chunks, query) {
     const scores = new Map();
     const qTerms = tokenize(query);
@@ -107,23 +191,22 @@ export function fuzzyTitleAliasScores(chunks, query) {
         return scores;
     for (let docId = 0; docId < chunks.length; docId++) {
         const c = chunks[docId];
-        const targets = [c.title, ...(c.meta?.aliases || [])].filter(Boolean);
+        const tTerms = targetTokens(c);
         let maxScore = 0;
-        for (const target of targets) {
-            const tTerms = tokenize(target);
-            for (const qt of qTerms) {
-                if (qt.length < 3)
+        for (const qt of qTerms) {
+            if (qt.length < 3)
+                continue;
+            const maxDist = Math.min(2, Math.floor(qt.length / 3));
+            for (const tt of tTerms) {
+                if (tt.length < 3)
                     continue;
-                for (const tt of tTerms) {
-                    if (tt.length < 3)
-                        continue;
-                    const maxDist = Math.min(2, Math.floor(qt.length / 3));
-                    const dist = editDistance(qt, tt);
-                    if (dist <= maxDist) {
-                        const similarity = 1 - dist / Math.max(qt.length, tt.length);
-                        if (similarity > maxScore)
-                            maxScore = similarity;
-                    }
+                // exact same decision as editDistance(qt, tt) <= maxDist, without the
+                // full O(len²) matrix (issue #193)
+                const dist = editDistanceAtMost(qt, tt, maxDist);
+                if (dist !== null) {
+                    const similarity = 1 - dist / Math.max(qt.length, tt.length);
+                    if (similarity > maxScore)
+                        maxScore = similarity;
                 }
             }
         }

package/dist/markdown-parser.d.ts

@@ -21,8 +21,70 @@ export interface StructuralChunk {
 }
 export declare function parseMarkdownBlocks(body: string): MarkdownBlock[];
 export declare function resolveChunkBudget(tokens?: number, defaultMax?: number): number;
+/**
+ * issue #202: script-calibrated token estimate for the sentencepiece E5/BGE
+ * vocab family — the fast-path alternative to running the real tokenizer per
+ * block. Ratios are calibrated so the estimate errs slightly HIGH: a budget
+ * checked against this estimate never overflows the model's real maxTokens.
+ *   Latin/digits/punctuation ≈ 4 chars/token, Cyrillic ≈ 1.8 chars/token
+ *   (RU systematically under-chunked by the old char budget — the point of
+ *   this issue), CJK ≈ 1 token/char, whitespace mostly merges into the
+ *   following subword so it counts a little.
+ */
+export declare function estimateTokens(text: string): number;
+/** Token measure: injected exact counter when available, else the calibrated estimate. */
+export type TokenCounter = (text: string) => number;
+export interface ChunkBudget {
+    /** Max measured size a single chunk may reach before it is split/flushed. */
+    budget: number;
+    /** Measures a text in the same unit the budget is expressed in. */
+    measure: TokenCounter;
+    /** Unit name for diagnostics/tests. */
+    unit: 'chars' | 'tokens';
+}
+/** Char budget (pre-#202 behavior) vs token budget (issue #202). */
+export declare function resolveChunkingBudget(opts: {
+    maxChunk?: number;
+    maxChunkTokens?: number;
+    countTokens?: TokenCounter;
+}): ChunkBudget;
+/**
+ * issue #202: the DEFAULT chunk budget in tokens, derived from the embedding
+ * adapter's context window. Capped at 512 — a passage much larger than that
+ * dilutes retrieval granularity even for models with 8k+ context (bge-m3).
+ * Returns undefined for adapters without a known maxTokens, which keeps the
+ * legacy char budget instead of guessing.
+ */
+export declare function defaultChunkTokenBudget(adapter: {
+    maxTokens?: number;
+}): number | undefined;
 export declare function chunkMarkdownStructural(input: string | MarkdownBlock[], opts?: number | {
     maxChunk?: number;
     targetTokens?: number;
+    maxChunkTokens?: number;
+    countTokens?: TokenCounter;
 }): StructuralChunk[];
+export interface OversizedPiece {
+    text: string;
+    /** 0-based block-relative range of REAL source lines backing this piece. */
+    startLine: number;
+    endLine: number;
+}
 export declare function splitOversizedBlock(text: string, maxChunk: number, blockType?: MarkdownBlock['type']): string[];
+/**
+ * issue #202: oversized-block splitting under an arbitrary measure (chars or
+ * tokens). The heavy lifting (fence repeats, table header repeats, #167 line
+ * ranges) stays in the char-based splitOversizedBlockWithRanges; the token
+ * budget is converted to a char budget for THIS block via its own chars-per-
+ * measured-unit ratio, then every piece is verified — script-skew inside the
+ * block (ASCII header + Cyrillic body) is caught by a greedy re-split.
+ */
+export declare function splitOversizedByMeasure(text: string, budget: number, measure: TokenCounter, blockType?: MarkdownBlock['type']): OversizedPiece[];
+/**
+ * Issue #167: like splitOversizedBlock, but each piece also reports the
+ * block-relative range of source lines it was built from. Synthetic lines
+ * added to keep pieces self-contained (fence repeats, table header repeats)
+ * do NOT count — only the first piece's opening fence/header and a real
+ * closing fence belong to the source.
+ */
+export declare function splitOversizedBlockWithRanges(text: string, maxChunk: number, blockType?: MarkdownBlock['type']): OversizedPiece[];

package/dist/markdown-parser.js

@@ -139,9 +139,63 @@ export function resolveChunkBudget(tokens, defaultMax = 1200) {
     }
     return defaultMax;
 }
+/**
+ * issue #202: script-calibrated token estimate for the sentencepiece E5/BGE
+ * vocab family — the fast-path alternative to running the real tokenizer per
+ * block. Ratios are calibrated so the estimate errs slightly HIGH: a budget
+ * checked against this estimate never overflows the model's real maxTokens.
+ *   Latin/digits/punctuation ≈ 4 chars/token, Cyrillic ≈ 1.8 chars/token
+ *   (RU systematically under-chunked by the old char budget — the point of
+ *   this issue), CJK ≈ 1 token/char, whitespace mostly merges into the
+ *   following subword so it counts a little.
+ */
+export function estimateTokens(text) {
+    let tokens = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if (c >= 0x0400 && c <= 0x04ff)
+            tokens += 0.55; // Cyrillic (+ Cyrillic supplement edges)
+        else if ((c >= 0x3040 && c <= 0x30ff) || // hiragana / katakana
+            (c >= 0x3400 && c <= 0x4dbf) || // CJK ext A
+            (c >= 0x4e00 && c <= 0x9fff) || // CJK unified
+            (c >= 0xff00 && c <= 0xffef) // fullwidth forms
+        ) {
+            tokens += 1.0;
+        }
+        else if (c === 0x20 || (c >= 0x09 && c <= 0x0d))
+            tokens += 0.08;
+        else if (c < 0x80)
+            tokens += 0.25; // ASCII (latin, digits, punctuation, markdown syntax)
+        else
+            tokens += 0.35; // other scripts / symbols — conservative middle ground
+    }
+    return Math.ceil(tokens);
+}
+/** Char budget (pre-#202 behavior) vs token budget (issue #202). */
+export function resolveChunkingBudget(opts) {
+    if (opts.maxChunkTokens && Number.isFinite(opts.maxChunkTokens) && opts.maxChunkTokens > 0) {
+        const budget = Math.max(32, Math.round(opts.maxChunkTokens));
+        return { budget, measure: opts.countTokens ?? estimateTokens, unit: 'tokens' };
+    }
+    const budget = resolveChunkBudget(undefined, opts.maxChunk ?? 1200);
+    return { budget, measure: (t) => t.length, unit: 'chars' };
+}
+/**
+ * issue #202: the DEFAULT chunk budget in tokens, derived from the embedding
+ * adapter's context window. Capped at 512 — a passage much larger than that
+ * dilutes retrieval granularity even for models with 8k+ context (bge-m3).
+ * Returns undefined for adapters without a known maxTokens, which keeps the
+ * legacy char budget instead of guessing.
+ */
+export function defaultChunkTokenBudget(adapter) {
+    const mt = adapter?.maxTokens;
+    if (!mt || !Number.isFinite(mt) || mt <= 0)
+        return undefined;
+    return Math.min(Math.round(mt), 512);
+}
 export function chunkMarkdownStructural(input, opts) {
     const options = typeof opts === 'number' ? { maxChunk: opts } : (opts || {});
-    const maxChunk = resolveChunkBudget(options.targetTokens, options.maxChunk ?? 1200);
+    const { budget: maxChunk, measure } = resolveChunkingBudget(options);
     const blocks = typeof input === 'string' ? parseMarkdownBlocks(input) : input;
     const chunks = [];
     const headingStack = [];
@@ -149,6 +203,8 @@ export function chunkMarkdownStructural(input, opts) {
     let currentLen = 0;
     let groupStartLine = 0;
     let groupEndLine = 0;
+    // measured size of the '\n\n' joiner — 2 in char mode, ~1 in token mode
+    const joinerSize = measure('\n\n');
     const flushGroup = () => {
         if (currentGroup.length === 0)
             return;
@@ -180,26 +236,25 @@ export function chunkMarkdownStructural(input, opts) {
         const blockText = block.text.trim();
         if (!blockText)
             continue;
-        if (blockText.length > maxChunk) {
+        if (measure(blockText) > maxChunk) {
             flushGroup();
             const headingPath = headingStack.map(h => h.heading);
-            const subPieces = splitOversizedBlock(blockText, maxChunk, block.type);
-            let lineCursor = block.startLine;
-            for (let idx = 0; idx < subPieces.length; idx++) {
-                const piece = subPieces[idx];
-                const pieceLineCount = piece.split('\n').length;
+            // Issue #167: pieces carry the block-relative range of REAL source
+            // lines backing them — synthetic fence/header repeats must not advance
+            // the line cursor, or every later sub-chunk drifts down the file.
+            const subPieces = splitOversizedByMeasure(blockText, maxChunk, measure, block.type);
+            for (const piece of subPieces) {
                 chunks.push({
                     heading: headingPath.at(-1) ?? '',
                     headingPath: [...headingPath],
-                    text: piece,
-                    startLine: lineCursor,
-                    endLine: Math.min(block.endLine, lineCursor + pieceLineCount - 1),
+                    text: piece.text,
+                    startLine: block.startLine + piece.startLine,
+                    endLine: Math.min(block.endLine, block.startLine + piece.endLine),
                 });
-                lineCursor += pieceLineCount;
             }
             continue;
         }
-        const addedLen = currentLen === 0 ? blockText.length : currentLen + 2 + blockText.length;
+        const addedLen = currentLen === 0 ? measure(blockText) : currentLen + joinerSize + measure(blockText);
         if (addedLen > maxChunk && currentGroup.length > 0) {
             flushGroup();
         }
@@ -207,7 +262,7 @@ export function chunkMarkdownStructural(input, opts) {
             groupStartLine = block.startLine;
         }
         currentGroup.push(blockText);
-        currentLen += (currentGroup.length === 1 ? 0 : 2) + blockText.length;
+        currentLen += (currentGroup.length === 1 ? 0 : joinerSize) + measure(blockText);
         groupEndLine = block.endLine;
     }
     flushGroup();
@@ -228,9 +283,121 @@ function splitLongLine(line, maxChunk) {
     return pieces;
 }
 export function splitOversizedBlock(text, maxChunk, blockType) {
+    return splitOversizedBlockWithRanges(text, maxChunk, blockType).map((p) => p.text);
+}
+/**
+ * issue #202: oversized-block splitting under an arbitrary measure (chars or
+ * tokens). The heavy lifting (fence repeats, table header repeats, #167 line
+ * ranges) stays in the char-based splitOversizedBlockWithRanges; the token
+ * budget is converted to a char budget for THIS block via its own chars-per-
+ * measured-unit ratio, then every piece is verified — script-skew inside the
+ * block (ASCII header + Cyrillic body) is caught by a greedy re-split.
+ */
+export function splitOversizedByMeasure(text, budget, measure, blockType) {
+    if (measure(text) <= budget) {
+        return [{ text, startLine: 0, endLine: Number.MAX_SAFE_INTEGER }];
+    }
+    // char equivalent of the budget for this block's script mix; fall back to
+    // a plain char split with the raw budget when measuring is degenerate
+    const measured = Math.max(1, measure(text));
+    const charsPerUnit = text.length / measured;
+    const charBudget = Math.max(32, Math.floor(budget * charsPerUnit));
+    const pieces = splitOversizedBlockWithRanges(text, charBudget, blockType);
+    const out = [];
+    for (const piece of pieces) {
+        if (measure(piece.text) <= budget) {
+            out.push(piece);
+            continue;
+        }
+        // script-skew safety net: greedy line/word accumulation under measure;
+        // the greedy splitter tracks consumed source lines so #167 ranges stay real
+        const spanLines = piece.endLine - piece.startLine + 1;
+        const textLines = piece.text.split('\n');
+        // when synthetic lines (fence/table repeats) inflated the piece, the text
+        // has more lines than the source span — clamp keeps ranges inside the block
+        const lineStride = textLines.length > spanLines ? spanLines / textLines.length : 1;
+        for (const sub of greedySplitByMeasure(piece.text, budget, measure)) {
+            const startLine = piece.startLine + Math.min(spanLines - 1, Math.floor(sub.startLine * lineStride));
+            const endLine = piece.startLine + Math.min(spanLines - 1, Math.max(sub.startLine, Math.floor(sub.endLine * lineStride)));
+            out.push({ text: sub.text, startLine, endLine });
+        }
+    }
+    return out;
+}
+function greedySplitByMeasure(text, budget, measure) {
+    const out = [];
+    const lines = text.split('\n');
+    let bufStart = 0;
+    let bufEnd = 0;
+    let current = '';
+    const flush = (uptoLine) => {
+        if (current.trim())
+            out.push({ text: current.trim(), startLine: bufStart, endLine: uptoLine });
+        current = '';
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const candidate = current ? `${current}\n${line}` : line;
+        if (measure(candidate) <= budget) {
+            if (!current)
+                bufStart = i;
+            current = candidate;
+            bufEnd = i;
+            continue;
+        }
+        flush(i - 1);
+        if (measure(line) <= budget) {
+            bufStart = i;
+            current = line;
+            bufEnd = i;
+            continue;
+        }
+        // single line over budget: word-level accumulation, all pieces stay on
+        // this line's range
+        const words = line.split(/\s+/);
+        let wordBuf = '';
+        for (const word of words) {
+            const wc = wordBuf ? `${wordBuf} ${word}` : word;
+            if (measure(wc) <= budget) {
+                wordBuf = wc;
+                continue;
+            }
+            if (wordBuf.trim())
+                out.push({ text: wordBuf.trim(), startLine: i, endLine: i });
+            if (measure(word) <= budget) {
+                wordBuf = word;
+                continue;
+            }
+            // monster token (no spaces): hard-slice by chars proportional to budget
+            const ratio = line.length / Math.max(1, measure(line));
+            const sliceLen = Math.max(8, Math.floor(budget * ratio));
+            let rest = word;
+            while (measure(rest) > budget && rest.length > sliceLen) {
+                out.push({ text: rest.slice(0, sliceLen), startLine: i, endLine: i });
+                rest = rest.slice(sliceLen);
+            }
+            wordBuf = rest;
+        }
+        if (wordBuf.trim()) {
+            bufStart = i;
+            current = wordBuf;
+            bufEnd = i;
+        }
+    }
+    flush(bufEnd);
+    return out;
+}
+/**
+ * Issue #167: like splitOversizedBlock, but each piece also reports the
+ * block-relative range of source lines it was built from. Synthetic lines
+ * added to keep pieces self-contained (fence repeats, table header repeats)
+ * do NOT count — only the first piece's opening fence/header and a real
+ * closing fence belong to the source.
+ */
+export function splitOversizedBlockWithRanges(text, maxChunk, blockType) {
     const lines = text.split('\n');
     if (lines.length <= 1) {
-        return splitLongLine(text, maxChunk);
+        return splitLongLine(text, maxChunk).map((piece) => ({ text: piece, startLine: 0, endLine: 0 }));
     }
     // If code block with opening fence
     if (blockType === 'code' && lines.length > 2 && /^(\s*)(`{3,}|~{3,})/.test(lines[0])) {
@@ -241,17 +408,30 @@ export function splitOversizedBlock(text, maxChunk, blockType) {
         const pieces = [];
         let currentCode = [];
         let currentLen = openFence.length + closeFence.length + 2;
-        for (const line of innerLines) {
+        // The opening fence is a real source line only in the first piece; a
+        // real closing fence only in the final one.
+        const flush = (isFinal) => {
+            const firstReal = pieces.length === 0 ? 0 : currentCode[0].srcIdx;
+            const lastReal = isFinal && hasCloseFence ? lines.length - 1 : currentCode[currentCode.length - 1].srcIdx;
+            pieces.push({
+                text: [openFence, ...currentCode.map((c) => c.line), closeFence].join('\n'),
+                startLine: firstReal,
+                endLine: lastReal,
+            });
+        };
+        for (let offset = 0; offset < innerLines.length; offset++) {
+            const line = innerLines[offset];
+            const srcIdx = 1 + offset;
             if (currentLen + line.length + 1 > maxChunk && currentCode.length > 0) {
-                pieces.push([openFence, ...currentCode, closeFence].join('\n'));
+                flush(false);
                 currentCode = [];
                 currentLen = openFence.length + closeFence.length + 2;
             }
-            currentCode.push(line);
+            currentCode.push({ line, srcIdx });
             currentLen += line.length + 1;
         }
         if (currentCode.length > 0) {
-            pieces.push([openFence, ...currentCode, closeFence].join('\n'));
+            flush(true);
         }
         if (pieces.length > 0)
             return pieces;
@@ -264,17 +444,27 @@ export function splitOversizedBlock(text, maxChunk, blockType) {
         const pieces = [];
         let currentRows = [];
         let currentLen = headerLen;
-        for (const row of dataRows) {
+        const flush = () => {
+            const firstReal = pieces.length === 0 ? 0 : currentRows[0].srcIdx;
+            pieces.push({
+                text: [...headerRows, ...currentRows.map((r) => r.row)].join('\n'),
+                startLine: firstReal,
+                endLine: currentRows[currentRows.length - 1].srcIdx,
+            });
+        };
+        for (let offset = 0; offset < dataRows.length; offset++) {
+            const row = dataRows[offset];
+            const srcIdx = 2 + offset;
             if (currentLen + row.length + 1 > maxChunk && currentRows.length > 0) {
-                pieces.push([...headerRows, ...currentRows].join('\n'));
+                flush();
                 currentRows = [];
                 currentLen = headerLen;
             }
-            currentRows.push(row);
+            currentRows.push({ row, srcIdx });
             currentLen += row.length + 1;
         }
         if (currentRows.length > 0) {
-            pieces.push([...headerRows, ...currentRows].join('\n'));
+            flush();
         }
         if (pieces.length > 0)
             return pieces;
@@ -283,29 +473,36 @@ export function splitOversizedBlock(text, maxChunk, blockType) {
     const pieces = [];
     let currentLines = [];
     let currentLen = 0;
-    for (const line of lines) {
+    const flush = () => {
+        pieces.push({
+            text: currentLines.map((l) => l.line).join('\n').trim(),
+            startLine: currentLines[0].srcIdx,
+            endLine: currentLines[currentLines.length - 1].srcIdx,
+        });
+    };
+    for (let srcIdx = 0; srcIdx < lines.length; srcIdx++) {
+        const line = lines[srcIdx];
         if (currentLen + line.length + 1 > maxChunk && currentLines.length > 0) {
-            pieces.push(currentLines.join('\n').trim());
+            flush();
             currentLines = [];
             currentLen = 0;
         }
         if (line.length > maxChunk) {
             if (currentLines.length > 0) {
-                pieces.push(currentLines.join('\n').trim());
+                flush();
                 currentLines = [];
             }
-            const splitLines = splitLongLine(line, maxChunk);
-            for (const piece of splitLines) {
-                pieces.push(piece);
+            for (const piece of splitLongLine(line, maxChunk)) {
+                pieces.push({ text: piece, startLine: srcIdx, endLine: srcIdx });
             }
             currentLen = 0;
             continue;
         }
-        currentLines.push(line);
+        currentLines.push({ line, srcIdx });
         currentLen += line.length + 1;
     }
     if (currentLines.length > 0) {
-        pieces.push(currentLines.join('\n').trim());
+        flush();
     }
     return pieces;
 }

package/dist/mcp.d.ts

@@ -4,6 +4,64 @@
  * via a zero-dependency JSON-RPC 2.0 stdio transport per the MCP specification.
  */
 import readline from 'node:readline';
+/**
+ * Protocol versions this server can speak (issue #197), newest first.
+ * `initialize` echoes the client's requested version when we support it,
+ * otherwise answers with MCP_SUPPORTED_VERSIONS[0].
+ */
+export declare const MCP_SUPPORTED_VERSIONS: string[];
+/**
+ * Resolves the protocol version to answer an `initialize` with: the client's
+ * exact request when supported, else the newest version we speak (the spec's
+ * "respond with another protocol version you support" branch).
+ */
+export declare function negotiateProtocolVersion(requested?: unknown): string;
+export interface McpClientChannelRequestOptions {
+    timeoutMs?: number;
+}
+/**
+ * Reverse channel for server→client JSON-RPC requests (issue #197) — today
+ * only `sampling/createMessage`. Both transports build one: stdio writes
+ * requests to its stdout and matches response lines by id; HTTP pushes them
+ * onto the GET /mcp SSE stream and matches POSTed responses by id.
+ */
+export interface McpClientChannel {
+    request(method: string, params?: any, opts?: McpClientChannelRequestOptions): Promise<any>;
+    /**
+     * Feeds a client message in. Returns true when it resolved a pending
+     * request; false means the message is a client request/notification and
+     * belongs to the normal handler.
+     */
+    handleResponse(msg: any): boolean;
+}
+/** Server→client requests that outlive this wait degrade, not hang (issue #197). */
+export declare const DEFAULT_SAMPLING_TIMEOUT_MS = 60000;
+/** `sampling/createMessage` requires maxTokens — a grounded citation answer fits comfortably. */
+export declare const DEFAULT_SAMPLING_MAX_TOKENS = 1024;
+export declare function samplingTimeoutMs(envValue?: string): number;
+/**
+ * Builds a client channel over a raw sink. Ids are prefixed `mdss-srv-` so
+ * they can never collide with the client's own request ids in either
+ * direction's logs or pending maps.
+ */
+export declare function createClientChannel(send: (msg: any) => void): McpClientChannel;
+/**
+ * A sampling-backed synthesis hook for the RAG layer (issue #197): returns
+ * null unless the client both declared the `sampling` capability at
+ * initialize AND a reverse channel exists — otherwise ask_knowledge_base goes
+ * straight to the local extractive answer. Any in-flight failure (client
+ * refusal, timeout, non-text content) throws and degrades the same way.
+ */
+export declare function createSamplingSynthesizer(state: {
+    channel?: McpClientChannel;
+    clientCapabilities?: any;
+}): {
+    fn: (req: {
+        system: string;
+        user: string;
+    }) => Promise<string>;
+    used: () => boolean;
+} | null;
 export declare const MCP_TOOLS: ({
     name: string;
     description: string;
@@ -276,12 +334,23 @@ export declare const MCP_PROMPTS: {
         required: boolean;
     }[];
 }[];
-export declare function handleMcpRequest(req: any, state: {
+/**
+ * Shared state for both MCP transports (stdio + Streamable HTTP): the
+ * transports own the extras — `channel` (server→client requests, issue #197),
+ * `clientCapabilities` (recorded at initialize), `output` (stdio sink, test seam).
+ */
+export interface McpHandlerState {
     loaded: any;
     cacheDir: string;
     offline: boolean;
     embedFn?: any;
-}): Promise<any | null>;
+    channel?: McpClientChannel;
+    clientCapabilities?: any;
+    output?: {
+        write(chunk: string): void;
+    };
+}
+export declare function handleMcpRequest(req: any, state: McpHandlerState): Promise<any | null>;
 export interface StartMcpServerOptions {
     indexDir: string;
     cacheDir: string;
@@ -290,9 +359,23 @@ export interface StartMcpServerOptions {
     ignore?: string[];
     offline?: boolean;
     embedFn?: any;
+    /** Stdio source (default process.stdin) — test/embedding seam (issue #197). */
+    input?: NodeJS.ReadableStream;
+    /** Stdio sink (default process.stdout) — test/embedding seam (issue #197). */
+    output?: {
+        write(chunk: string): void;
+    };
     log?: (msg: string) => void;
 }
 export declare function startMcpServer(opts: StartMcpServerOptions): Promise<{
-    state: any;
+    state: McpHandlerState;
     rl: readline.Interface;
 }>;
+/**
+ * One guarded, in-order stdio JSON-RPC exchange (issues #180/#185): caps the
+ * line length, turns JSON parse failures into `-32700`, and converts ANY
+ * handler escape into a `-32603` response instead of an unhandled rejection
+ * that would kill the daemon.
+ */
+export declare const MAX_STDIO_LINE_CHARS: number;
+export declare function handleStdioLine(line: string, state: McpHandlerState): Promise<void>;