sanook-cli 0.4.0 → 0.5.0

package/dist/repomap.js

@@ -0,0 +1,93 @@
+import { readFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { runGit, isGitRepo } from './git.js';
+// repo map = symbol map คร่าวๆ ของ repo (zero-dep, regex per ภาษา) inject ตอน session start
+// ช่วย agent เลือกไฟล์ถูกโดยไม่ต้อง grep/read ทีละไฟล์ — เลียน Aider repo-map (เวอร์ชัน lightweight)
+const MAX_FILES = 400;
+const MAX_FILE_BYTES = 32 * 1024;
+const SYMS_PER_FILE = 12;
+const SOURCE_EXT = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs',
+    '.java', '.rb', '.c', '.h', '.cpp', '.hpp', '.cs', '.php', '.swift', '.kt',
+]);
+const IGNORE_DIR = /(^|\/)(node_modules|dist|build|coverage|\.next|\.cache|\.git|vendor|__pycache__)(\/|$)/;
+// regex ดึง top-level / exported symbol — หลายภาษา รวมกัน dedup
+const SYMBOL_PATTERNS = [
+    /^export\s+(?:default\s+)?(?:async\s+)?(?:function|class|const|interface|type|enum)\s+([A-Za-z0-9_$]+)/gm, // TS/JS export
+    /^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm, // JS function
+    /^(?:export\s+)?class\s+([A-Za-z0-9_$]+)/gm, // JS class
+    /^(?:def|class)\s+([A-Za-z0-9_]+)/gm, // Python
+    /^func\s+(?:\([^)]*\)\s+)?([A-Za-z0-9_]+)/gm, // Go
+    /^(?:pub\s+)?(?:fn|struct|enum|trait|impl)\s+([A-Za-z0-9_]+)/gm, // Rust
+];
+function extractSymbols(content) {
+    const found = new Set();
+    for (const re of SYMBOL_PATTERNS) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            if (m[1])
+                found.add(m[1]);
+            if (found.size >= SYMS_PER_FILE * 3)
+                break;
+        }
+    }
+    return [...found].slice(0, SYMS_PER_FILE);
+}
+function isSource(rel) {
+    return SOURCE_EXT.has(extname(rel).toLowerCase()) && !IGNORE_DIR.test(rel);
+}
+// คืน null = git ล้มชั่วคราว (อย่า cache, ลองใหม่รอบหน้า) · [] = ไม่ใช่ git repo จริงๆ (cache ได้)
+async function listFiles(cwd) {
+    if (await isGitRepo(cwd)) {
+        try {
+            return (await runGit(['ls-files'], cwd)).split('\n').filter(Boolean);
+        }
+        catch {
+            return null; // ls-files ล้ม (เช่น maxBuffer / index lock) ≠ repo ว่าง
+        }
+    }
+    return [];
+}
+let cached = null;
+/**
+ * โครงสร้าง symbol ของ repo (cap ที่ maxChars) — cache ต่อ process ต่อ cwd (โครงสร้างไม่ค่อยเปลี่ยนกลาง session)
+ * คืน '' ถ้าไม่ใช่ git repo / ไม่มี source file (เช่น brain vault ที่มีแต่ markdown)
+ */
+export async function loadRepoMap(cwd = process.cwd(), maxChars = 4000) {
+    if (cached && cached.cwd === cwd)
+        return cached.map;
+    const raw = await listFiles(cwd);
+    if (raw === null)
+        return ''; // git ล้มชั่วคราว → คืนว่างแต่ไม่ cache (ลองใหม่รอบหน้า)
+    const files = raw.filter(isSource).slice(0, MAX_FILES);
+    if (!files.length) {
+        cached = { cwd, map: '' };
+        return '';
+    }
+    const entries = await Promise.all(files.map(async (rel) => {
+        try {
+            const content = (await readFile(join(cwd, rel), 'utf8')).slice(0, MAX_FILE_BYTES);
+            const syms = extractSymbols(content);
+            return syms.length ? `${rel}: ${syms.join(', ')}` : rel;
+        }
+        catch {
+            return rel;
+        }
+    }));
+    let body = '';
+    for (const e of entries) {
+        if (body.length + e.length + 1 > maxChars) {
+            body += '\n…';
+            break;
+        }
+        body += (body ? '\n' : '') + e;
+    }
+    const map = `<repo_map note="symbol คร่าวๆ ของ repo (อาจไม่ครบ/ไม่เป๊ะ) — ใช้ glob/grep/read_file ยืนยันก่อนแก้">\n${body}\n</repo_map>`;
+    cached = { cwd, map };
+    return map;
+}
+/** เคลียร์ cache (สำหรับ test / เมื่อ cwd เปลี่ยน) */
+export function clearRepoMapCache() {
+    cached = null;
+}

package/dist/search/chunk.js

@@ -0,0 +1,158 @@
+// ============================================================================
+// src/search/chunk.ts — ONE generic, heading-aware markdown chunker.
+//
+// arra-oracle ships five hardcoded type parsers (resonance/learning/retro/
+// distillation/security-corpus), each splitting on its own header convention.
+// We replace all five with a single type-agnostic chunker: split on ATX
+// headings, fold sub-MIN sections forward so we never emit a tiny chunk, and key
+// each chunk by a stable hash of (path)#ordinal so re-indexing a file replaces
+// exactly its chunks (no posting creep — see index-core.addDoc).
+//
+// Everything is pure (no fs) and DEFENSIVE: malformed frontmatter, nested YAML,
+// or a stray [[ inside a code fence degrade to "no frontmatter / no links"
+// rather than throwing. We must never block indexing a real, messy vault file.
+// ============================================================================
+const MIN_CHARS = 120; // sections shorter than this fold into the next chunk
+/** deterministic short hash of a path (fnv-1a → base36) — no crypto dep, stable chunk ids. */
+export function pathHash(path) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < path.length; i++) {
+        h ^= path.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+/** split a leading `---\n…\n---` frontmatter block from the body. Defensive: no block ⇒ {} + full md. */
+export function parseFrontmatter(md) {
+    const empty = { tags: [] };
+    if (!md.startsWith('---'))
+        return { data: empty, body: md };
+    const end = md.indexOf('\n---', 3);
+    if (end === -1)
+        return { data: empty, body: md };
+    const block = md.slice(3, end).trim();
+    const body = md.slice(md.indexOf('\n', end + 1) + 1).replace(/^\n+/, '');
+    const data = { tags: [] };
+    const lines = block.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1].toLowerCase();
+        const val = m[2].trim();
+        if (key === 'note_type' || key === 'notetype')
+            data.noteType = stripQuotes(val);
+        else if (key === 'parent')
+            data.parent = unwrapLink(val);
+        else if (key === 'up')
+            data.up = unwrapLink(val);
+        else if (key === 'tags') {
+            if (val.startsWith('['))
+                data.tags = inlineList(val);
+            else if (val)
+                data.tags = [stripQuotes(val)];
+            else {
+                // YAML block list: subsequent "- item" lines
+                for (let j = i + 1; j < lines.length && /^\s*-\s+/.test(lines[j]); j++) {
+                    data.tags.push(stripQuotes(lines[j].replace(/^\s*-\s+/, '').trim()));
+                }
+            }
+        }
+    }
+    return { data, body };
+}
+function stripQuotes(s) {
+    return s.replace(/^["']|["']$/g, '').trim();
+}
+function unwrapLink(s) {
+    const m = /\[\[([^\]]+)\]\]/.exec(s);
+    return (m ? m[1] : stripQuotes(s)).split('|')[0].trim();
+}
+function inlineList(s) {
+    return s
+        .replace(/^\[|\]$/g, '')
+        .split(',')
+        .map((t) => stripQuotes(t))
+        .filter(Boolean);
+}
+/** extract [[wikilink]] targets (alias after | dropped), ignoring fenced code blocks. Deduped. */
+export function extractWikilinks(md) {
+    const noFences = md.replace(/```[\s\S]*?```/g, ' ').replace(/`[^`]*`/g, ' ');
+    const out = new Set();
+    for (const m of noFences.matchAll(/\[\[([^\]]+)\]\]/g)) {
+        const target = m[1].split('|')[0].split('#')[0].trim();
+        if (target)
+            out.add(target);
+    }
+    return [...out];
+}
+/** split body into sections at ATX headings (fenced code blocks are not headings). */
+function splitSections(md) {
+    const sections = [];
+    let cur = { heading: '', body: '' };
+    let inFence = false;
+    for (const line of md.split('\n')) {
+        if (/^\s*(```|~~~)/.test(line))
+            inFence = !inFence;
+        const m = inFence ? null : /^(#{1,6})\s+(.*\S)\s*$/.exec(line);
+        if (m) {
+            if (cur.heading || cur.body.trim())
+                sections.push(cur);
+            cur = { heading: m[2].trim(), body: '' };
+        }
+        else {
+            cur.body += `${line}\n`;
+        }
+    }
+    if (cur.heading || cur.body.trim())
+        sections.push(cur);
+    return sections;
+}
+/** greedily pack sections so no chunk is below MIN_CHARS; the first section's heading labels the group. */
+function packSections(sections) {
+    const out = [];
+    let groupHeading = null;
+    let buf = '';
+    const flush = () => {
+        if (buf.trim())
+            out.push({ heading: groupHeading ?? '', body: buf.trim() });
+        buf = '';
+        groupHeading = null;
+    };
+    for (const s of sections) {
+        if (groupHeading === null) {
+            groupHeading = s.heading;
+            buf += s.body;
+        }
+        else {
+            if (s.heading)
+                buf += `\n${s.heading}\n`;
+            buf += s.body;
+        }
+        if (buf.trim().length >= MIN_CHARS)
+            flush();
+    }
+    flush();
+    return out;
+}
+/**
+ * Parse a markdown file into frontmatter + wikilink edges + heading-aware chunks.
+ * Pure and total — any structural weirdness degrades, never throws.
+ */
+export function chunkMarkdown(path, md) {
+    // normalize CRLF→LF — ไฟล์ vault บน Windows มัก CRLF; ไม่งั้น frontmatter ('\n---') + split พัง+ hash เพี้ยนข้ามแพลตฟอร์ม
+    md = md.replace(/\r\n/g, '\n');
+    const { data, body } = parseFrontmatter(md);
+    const links = extractWikilinks(body);
+    const packed = packSections(splitSections(body));
+    const hash = pathHash(path);
+    const chunks = packed.map((s, ordinal) => ({
+        id: `${hash}#${ordinal}`,
+        ordinal,
+        heading: s.heading,
+        text: s.body,
+    }));
+    // a file with a body but (after packing) no chunk — e.g. only whitespace — yields none; that's fine.
+    return { frontmatter: data, links, chunks };
+}

package/dist/search/embed-store.js

@@ -0,0 +1,187 @@
+// ============================================================================
+// src/search/embed-store.ts — OPTIONAL L1 semantic layer (BYOK embeddings).
+//
+// arra-oracle's semantic search needs LanceDB/sqlite-vec/Qdrant native binaries
+// (~100MB, no Windows for LanceDB) plus an Ollama model download and a Python
+// reranker sidecar. We need NONE of that: embeddings go through the user's
+// EXISTING ai-SDK provider key (embedMany), vectors live as a compact Float32
+// blob next to index.json, and cosine runs in-process over a BM25-PREFILTERED
+// candidate set (so we never scan the whole corpus per query). The whole layer is
+// LAZY — absent without a key, the engine degrades to BM25 with zero ceremony.
+//
+// Pure math (normalize, cosineTopK, (de)serialize) is unit-tested with fake
+// vectors; the only networked function is embedTexts(), kept thin.
+// ============================================================================
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { embedMany } from 'ai';
+import { appHomePath, persistenceEnabled } from '../brand.js';
+import { resolveEmbedder } from '../providers/registry.js';
+export const VECTORS_PATH = join(appHomePath('search'), 'vectors.json');
+export function emptyVectors(tag = '') {
+    return { tag, dim: 0, ids: [], data: new Float32Array(0) };
+}
+/** L2-normalize in place and return — lets cosine reduce to a dot product. */
+export function normalizeVec(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++)
+        sum += v[i] * v[i];
+    const norm = Math.sqrt(sum) || 1;
+    for (let i = 0; i < v.length; i++)
+        v[i] /= norm;
+    return v;
+}
+/** build a VectorIndex from rows (vectors normalized on the way in). */
+export function buildVectorIndex(tag, rows) {
+    if (!rows.length)
+        return emptyVectors(tag);
+    const dim = rows[0].vec.length;
+    if (dim <= 0)
+        return emptyVectors(tag);
+    const data = new Float32Array(rows.length * dim);
+    const ids = [];
+    for (let i = 0; i < rows.length; i++) {
+        if (rows[i].vec.length !== dim) {
+            throw new Error(`vector dimension mismatch for "${rows[i].id}": expected ${dim}, got ${rows[i].vec.length}`);
+        }
+        const v = Float32Array.from(rows[i].vec);
+        normalizeVec(v);
+        data.set(v, i * dim);
+        ids.push(rows[i].id);
+    }
+    return { tag, dim, ids, data };
+}
+/**
+ * Cosine top-K over a normalized vector index. `queryVec` is normalized here.
+ * An optional candidate allow-list (the BM25 prefilter) means cosine touches only
+ * a bounded set, never the whole corpus. Pure + deterministic.
+ */
+export function cosineTopK(vi, queryVec, k = 50, candidates) {
+    if (!vi.dim || !vi.ids.length)
+        return [];
+    const q = normalizeVec(Float32Array.from(queryVec));
+    if (q.length !== vi.dim)
+        return [];
+    const out = [];
+    for (let i = 0; i < vi.ids.length; i++) {
+        const id = vi.ids[i];
+        if (candidates && !candidates.has(id))
+            continue;
+        let dot = 0;
+        const base = i * vi.dim;
+        for (let d = 0; d < vi.dim; d++)
+            dot += q[d] * vi.data[base + d];
+        out.push({ id, score: dot });
+    }
+    return out
+        .sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+        .slice(0, k);
+}
+/** map id → row index, for incremental updates / lookups. */
+export function vectorIds(vi) {
+    return new Set(vi.ids);
+}
+const VEC_FILE_VERSION = 1;
+export function serializeVectors(vi) {
+    const buf = Buffer.from(vi.data.buffer, vi.data.byteOffset, vi.data.byteLength);
+    return { v: VEC_FILE_VERSION, tag: vi.tag, dim: vi.dim, ids: vi.ids, b64: buf.toString('base64') };
+}
+export function deserializeVectors(raw) {
+    const o = raw;
+    if (!o ||
+        o.v !== VEC_FILE_VERSION ||
+        typeof o.tag !== 'string' ||
+        typeof o.dim !== 'number' ||
+        !Number.isInteger(o.dim) ||
+        o.dim < 0 ||
+        !Array.isArray(o.ids) ||
+        !o.ids.every((id) => typeof id === 'string') ||
+        typeof o.b64 !== 'string') {
+        return emptyVectors();
+    }
+    // dim=0 is only valid for an empty index — normalize to emptyVectors so the invariant
+    // (dim===0 ⇔ ids=[] ⇔ data empty) holds at the deserializer boundary, not just downstream.
+    if (o.dim === 0)
+        return emptyVectors(o.tag);
+    const buf = Buffer.from(o.b64, 'base64');
+    if (buf.byteLength % 4 !== 0)
+        return emptyVectors(o.tag);
+    const arrayBuffer = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+    const data = new Float32Array(arrayBuffer);
+    // defensive: row count must match ids*dim, else treat as corrupt
+    if (data.length !== o.ids.length * o.dim)
+        return emptyVectors(o.tag);
+    return { tag: o.tag ?? '', dim: o.dim, ids: o.ids, data: Float32Array.from(data) };
+}
+// ---- fs boundary (mirrors store.ts: atomic, 0o600, persistence-gated) ----
+export async function loadVectors() {
+    try {
+        return deserializeVectors(JSON.parse(await readFile(VECTORS_PATH, 'utf8')));
+    }
+    catch {
+        return emptyVectors();
+    }
+}
+export async function saveVectors(vi) {
+    if (!persistenceEnabled())
+        return;
+    const dir = appHomePath('search');
+    await mkdir(dir, { recursive: true });
+    const tmp = join(dir, `vectors.${randomUUID()}.tmp`);
+    try {
+        await writeFile(tmp, `${JSON.stringify(serializeVectors(vi))}\n`, { mode: 0o600 });
+        await chmod(tmp, 0o600).catch(() => { });
+        await rename(tmp, VECTORS_PATH);
+    }
+    catch (e) {
+        await rm(tmp, { force: true }).catch(() => { });
+        throw e;
+    }
+}
+export async function vectorsMtimeMs() {
+    try {
+        return (await stat(VECTORS_PATH)).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+// ---- networked: embedding (the only part that talks to a provider) ----
+const BATCH = 64;
+/** resolve a BYOK embedder (or null). Thin re-export so search code imports from one place. */
+export function getEmbedder(spec) {
+    return resolveEmbedder(spec);
+}
+/**
+ * Embed many texts in batches with exponential backoff on rate limits. Returns
+ * one number[] per input, in order. Throws only if every retry fails — callers
+ * (engine/indexer) catch and fall back to BM25.
+ */
+export async function embedTexts(embedder, texts) {
+    const out = [];
+    for (let i = 0; i < texts.length; i += BATCH) {
+        const slice = texts.slice(i, i + BATCH);
+        out.push(...(await embedBatchWithRetry(embedder, slice)));
+    }
+    return out;
+}
+/** embed a single query string. */
+export async function embedQuery(embedder, text) {
+    return (await embedBatchWithRetry(embedder, [text]))[0];
+}
+async function embedBatchWithRetry(embedder, values, attempt = 0) {
+    try {
+        const { embeddings } = await embedMany({ model: embedder.model, values });
+        return embeddings;
+    }
+    catch (e) {
+        const msg = e.message ?? '';
+        const retryable = /429|rate.?limit|timeout|ECONNRESET|503|overloaded/i.test(msg);
+        if (retryable && attempt < 4) {
+            await new Promise((r) => setTimeout(r, 400 * 2 ** attempt));
+            return embedBatchWithRetry(embedder, values, attempt + 1);
+        }
+        throw e;
+    }
+}

package/dist/search/engine.js

@@ -0,0 +1,203 @@
+// ============================================================================
+// src/search/engine.ts — the search orchestrator (the one module callers use).
+//
+// Implements the degradation ladder as a single search() call:
+//   mode='fts'      → pure BM25 (the always-on floor)
+//   mode='semantic' → cosine over BYOK vectors (full recall)
+//   mode='hybrid'   → BM25 ⊕ cosine ⊕ memory-importance prior, fused by RRF
+//   mode='auto'     → hybrid when vectors are usable, else fts (the smart default)
+//
+// rankSearch() is the PURE core (index + optional vectors + optional query vector
+// in, ranked hits out) so the whole ranking pipeline unit-tests with zero disk
+// and zero network. search() is the thin disk/embedding wrapper: it caches the
+// index by mtime, caches query embeddings in an LRU, resolves a BYOK embedder
+// lazily, and on ANY embedding error degrades to BM25 with a `degraded` flag —
+// search must never throw at the floor.
+// ============================================================================
+import { readFile } from 'node:fs/promises';
+import { appHomePath } from '../brand.js';
+import { bm25Search, termList } from './index-core.js';
+import { rrfFuse } from './fuse.js';
+import { cosineTopK, embedQuery, getEmbedder, loadVectors, vectorsMtimeMs, } from './embed-store.js';
+import { indexMtimeMs, loadIndex } from './store.js';
+const CAND = 60; // candidate pool depth per leg before fusion/limit
+const SNIPPET_WIDTH = 64;
+/** ±width snippet around the first matched query term; falls back to the head for semantic-only hits. */
+function makeSnippet(text, qTerms, width = SNIPPET_WIDTH) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    const lower = flat.toLowerCase();
+    let pos = -1;
+    for (const t of qTerms) {
+        const i = lower.indexOf(t);
+        if (i >= 0 && (pos < 0 || i < pos))
+            pos = i;
+    }
+    if (pos < 0)
+        return flat.length > width * 2 ? `${flat.slice(0, width * 2).trim()}…` : flat;
+    const start = Math.max(0, pos - width);
+    const end = Math.min(flat.length, pos + width);
+    return `${start > 0 ? '…' : ''}${flat.slice(start, end).trim()}${end < flat.length ? '…' : ''}`;
+}
+/** ids of docs whose source is allowed (or all if no filter). */
+function sourceFilteredIds(index, sources) {
+    if (!sources)
+        return undefined;
+    const out = new Set();
+    for (const m of index.docs.values())
+        if (sources.has(m.source))
+            out.add(m.id);
+    return out;
+}
+/**
+ * PURE ranking core. Given the index, optional vectors, and an optional query
+ * vector, produce ranked hits per the requested mode. No disk, no network.
+ */
+export function rankSearch(index, query, opts = {}, vectors, queryVec) {
+    const mode = opts.mode ?? 'auto';
+    const limit = opts.limit ?? 8;
+    const sources = opts.sources?.length ? new Set(opts.sources) : undefined;
+    const qTerms = [...new Set(termList(query))];
+    const bm25 = bm25Search(index, query, CAND, sources);
+    const bm25Ids = bm25.map((h) => h.id);
+    const semanticPossible = !!(vectors && vectors.dim && queryVec && queryVec.length === vectors.dim);
+    const wantsSemantic = mode === 'semantic' || mode === 'hybrid' || mode === 'auto';
+    // resolve the executed mode + a degraded reason if the request can't be honored
+    let exec;
+    let degraded;
+    if (!wantsSemantic)
+        exec = 'fts';
+    else if (semanticPossible)
+        exec = mode === 'auto' ? 'hybrid' : mode;
+    else {
+        exec = 'fts';
+        if (mode === 'semantic' || mode === 'hybrid')
+            degraded = 'semantic-unavailable';
+    }
+    let orderedIds;
+    if (exec === 'fts') {
+        orderedIds = bm25Ids;
+    }
+    else {
+        const allowed = sourceFilteredIds(index, sources);
+        const cosine = cosineTopK(vectors, queryVec, CAND, allowed).filter((h) => index.docs.has(h.id));
+        const cosineIds = cosine.map((h) => h.id);
+        if (exec === 'semantic') {
+            orderedIds = cosineIds;
+        }
+        else {
+            // hybrid: BM25 ⊕ cosine ⊕ memory-importance prior, fused by rank (scale-free)
+            const priorIds = [...new Set([...bm25Ids, ...cosineIds])]
+                .map((id) => index.docs.get(id))
+                .filter((m) => !!m && m.source === 'memory' && m.importance != null)
+                .sort((a, b) => (b.importance ?? 0) - (a.importance ?? 0))
+                .map((m) => m.id);
+            orderedIds = rrfFuse([
+                { ids: bm25Ids },
+                { ids: cosineIds },
+                { ids: priorIds, weight: 0.4 },
+            ]);
+        }
+    }
+    const snippets = opts.snippets !== false;
+    const hits = [];
+    for (const id of orderedIds.slice(0, limit)) {
+        const m = index.docs.get(id);
+        if (!m)
+            continue;
+        hits.push({
+            id: m.id,
+            source: m.source,
+            title: m.title,
+            path: m.path,
+            noteType: m.noteType,
+            tags: m.tags,
+            score: 0, // rank-based; fused score isn't meaningful cross-mode, so we expose rank order
+            snippet: snippets ? makeSnippet(m.text, qTerms) : '',
+            importance: m.importance,
+        });
+    }
+    return { hits, mode: exec, degraded, total: new Set(orderedIds).size };
+}
+// ---- disk/embedding wrapper (the only impure part) -------------------------
+let indexCache = null;
+let vectorCache = null;
+const queryVecLRU = new Map(); // key = `${tag}\n${query}`
+const LRU_CAP = 100;
+/** cached index load — re-reads only when the on-disk index.json mtime changes. */
+async function cachedIndex() {
+    const mtime = await indexMtimeMs();
+    if (!indexCache || indexCache.mtime !== mtime) {
+        indexCache = { index: (await loadIndex()).index, mtime };
+    }
+    return indexCache.index;
+}
+async function cachedVectors() {
+    const mtime = await vectorsMtimeMs();
+    if (!vectorCache || vectorCache.mtime !== mtime) {
+        vectorCache = { vectors: await loadVectors(), mtime };
+    }
+    return vectorCache.vectors;
+}
+/** read an optional embeddingModel spec from ~/.sanook/config.json. */
+async function configEmbeddingModel() {
+    try {
+        const cfg = JSON.parse(await readFile(appHomePath('config.json'), 'utf8'));
+        return cfg.embeddingModel;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** drop in-process caches (tests + after a reindex in the same process). */
+export function resetSearchCaches() {
+    indexCache = null;
+    vectorCache = null;
+    queryVecLRU.clear();
+}
+/**
+ * The public search entrypoint. Loads the cached index, lazily resolves a BYOK
+ * embedder (opts → env SANOOK_EMBEDDING_MODEL → config → auto-detect), embeds the
+ * query (LRU-cached) only when semantic is wanted AND a usable same-tag vector set
+ * exists, then delegates to rankSearch. Any embedding failure degrades to BM25.
+ */
+export async function search(query, opts = {}) {
+    const index = await cachedIndex();
+    const mode = opts.mode ?? 'auto';
+    if (mode === 'fts')
+        return rankSearch(index, query, opts);
+    const spec = opts.embeddingModel ?? process.env.SANOOK_EMBEDDING_MODEL ?? (await configEmbeddingModel());
+    const embedder = getEmbedder(spec);
+    if (!embedder) {
+        const res = rankSearch(index, query, opts);
+        if (mode === 'semantic' || mode === 'hybrid')
+            res.degraded = 'no-embedder';
+        return res;
+    }
+    const vectors = await cachedVectors();
+    // a model change (different tag) invalidates the cache → behave as no-vectors until reindex
+    if (!vectors.dim || vectors.tag !== embedder.tag) {
+        const res = rankSearch(index, query, opts);
+        res.degraded = vectors.dim ? 'embedding-model-changed' : 'no-vectors';
+        return mode === 'auto' ? { ...res, degraded: undefined } : res;
+    }
+    let queryVec;
+    try {
+        const key = `${embedder.tag}\n${query}`;
+        const cached = queryVecLRU.get(key);
+        if (cached) {
+            queryVec = cached;
+        }
+        else {
+            queryVec = await embedQuery(embedder, query);
+            queryVecLRU.set(key, queryVec);
+            if (queryVecLRU.size > LRU_CAP)
+                queryVecLRU.delete(queryVecLRU.keys().next().value);
+        }
+    }
+    catch {
+        const res = rankSearch(index, query, opts); // embedding failed mid-query → BM25 floor
+        res.degraded = 'semantic-unavailable';
+        return res;
+    }
+    return rankSearch(index, query, opts, vectors, queryVec);
+}

package/dist/search/fuse.js

@@ -0,0 +1,35 @@
+// ============================================================================
+// src/search/fuse.ts — Reciprocal Rank Fusion (RRF).
+//
+// arra-oracle blends results with a hand-tuned linear formula
+// (fts*0.7 + vec*0.65 + 0.12*overlap) that mixes BM25 magnitudes with cosine
+// distances — two scales that are not comparable, so the weights are fragile and
+// corpus-dependent. RRF sidesteps the whole problem: it fuses on RANK, not score,
+// so a document's contribution depends only on where it placed in each list, not
+// on the (incomparable) raw numbers. A doc that ranks well in two lists naturally
+// sums two reciprocals and outranks a doc strong in only one. k=60 is the
+// standard Cormack et al. constant. Pure, deterministic, parameter-light.
+// ============================================================================
+const RRF_K = 60;
+/**
+ * Fuse N ranked id-lists into a single score map (higher = better).
+ * score(d) = Σ_lists weight / (k + rank_in_list(d)), rank 0-based.
+ */
+export function rrf(lists, k = RRF_K) {
+    const scores = new Map();
+    for (const list of lists) {
+        const w = list.weight ?? 1;
+        for (let rank = 0; rank < list.ids.length; rank++) {
+            const id = list.ids[rank];
+            scores.set(id, (scores.get(id) ?? 0) + w / (k + rank));
+        }
+    }
+    return scores;
+}
+/** RRF then sort → fused id list (best first), deterministic tie-break by id. */
+export function rrfFuse(lists, limit, k = RRF_K) {
+    const scores = rrf(lists, k);
+    const out = [...scores.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    const ids = out.map(([id]) => id);
+    return limit == null ? ids : ids.slice(0, limit);
+}