sanook-cli 0.4.0 → 0.5.1

package/dist/providers/registry.js

@@ -7,6 +7,7 @@ import { createMistral } from '@ai-sdk/mistral';
 import { createGroq } from '@ai-sdk/groq';
 import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
 import { resolveKeyFromEnv, assertDirectApiKey } from './keys.js';
+import { BRAND } from '../brand.js';
 // ────────────────────────────────────────────────────────────────────────────
 // PROVIDER TABLE — เพิ่มค่าย = เพิ่ม 1 entry (loop/cost/keys ไม่ต้องแตะ)
 // auth/format/OAuth-reject verify มิ.ย. 2026 (ดู Research/provider-connect-matrix)
@@ -20,6 +21,7 @@ export const PROVIDERS = {
         baseURL: 'https://api.anthropic.com/v1',
         requiresKey: true,
         keyFormat: /^sk-ant-api\d{2}-/,
+        keyExample: 'sk-ant-…', // สั้นพอไม่โดน redactKey (sk- + ≥6 chars ถึงโดนตัด)
         oauthRejectPrefixes: ['sk-ant-oat'], // Claude.ai subscription OAuth → banned
         models: {
             default: 'claude-opus-4-8',
@@ -39,6 +41,7 @@ export const PROVIDERS = {
         envFallbacks: ['GOOGLE_API_KEY', 'GEMINI_API_KEY'],
         requiresKey: true,
         keyFormat: /^AIza[0-9A-Za-z_-]{35}$/,
+        keyExample: 'AIza…',
         oauthRejectPrefixes: ['ya29.', 'AQ.'], // Google OAuth / restricted token → banned
         models: {
             default: 'gemini-2.5-pro',
@@ -57,6 +60,7 @@ export const PROVIDERS = {
         baseURL: 'https://api.openai.com/v1',
         requiresKey: true,
         keyFormat: /^sk-/,
+        keyExample: 'sk-…',
         models: {
             default: 'gpt-5.5',
             smart: 'gpt-5.5',
@@ -83,6 +87,7 @@ export const PROVIDERS = {
         envVar: 'XAI_API_KEY',
         requiresKey: true,
         keyFormat: /^xai-[A-Za-z0-9]{16,}$/,
+        keyExample: 'xai-…',
         // grok-4 (snapshot grok-4-0709) retired 2026-05-15 → redirect grok-4.3 (doc audit มิ.ย. 2026)
         models: { default: 'grok-4.3', smart: 'grok-4.3', grok: 'grok-4.3' },
         create: (key) => createXai({ apiKey: key }),
@@ -102,6 +107,7 @@ export const PROVIDERS = {
         envVar: 'GROQ_API_KEY',
         requiresKey: true,
         keyFormat: /^gsk_[A-Za-z0-9]{20,}$/,
+        keyExample: 'gsk_…',
         models: { default: 'llama-3.3-70b-versatile', fast: 'llama-3.3-70b-versatile' },
         create: (key) => createGroq({ apiKey: key }),
     },
@@ -215,6 +221,65 @@ export function specKey(spec) {
     const { provider, model } = parseSpec(spec);
     return `${provider}:${model}`;
 }
+/** หน้า console ที่ใช้สร้าง API key ต่อ provider — โชว์ในข้อความ error/wizard ("ไปเอา key ที่ไหน") */
+const CONSOLE_URLS = {
+    anthropic: 'https://console.anthropic.com/settings/keys',
+    google: 'https://aistudio.google.com/apikey',
+    openai: 'https://platform.openai.com/api-keys',
+    deepseek: 'https://platform.deepseek.com/api_keys',
+    xai: 'https://console.x.ai',
+    mistral: 'https://console.mistral.ai/api-keys',
+    groq: 'https://console.groq.com/keys',
+    minimax: 'https://platform.minimax.io',
+    glm: 'https://z.ai/manage-apikey/apikey-list',
+};
+export function consoleUrl(provider) {
+    return CONSOLE_URLS[provider];
+}
+/**
+ * provider นี้มี key ใน env ที่ "ใช้ได้จริง" ไหม — มี key + ผ่าน policy (ไม่ใช่ OAuth/subscription token
+ * หรือ format ผิด). ใช้ทั้ง first-run smart-skip และ -m flag เพื่อไม่ให้ข้าม wizard ทั้งที่ key ใช้ไม่ได้
+ * (เช่น export ANTHROPIC_API_KEY=sk-ant-oat… → ถูกแบน → ต้องเข้า wizard ไม่ใช่ขึ้น "พร้อมใช้")
+ */
+export function hasUsableEnvKey(provider) {
+    const cfg = PROVIDERS[provider];
+    if (!cfg)
+        return false;
+    if (!cfg.requiresKey)
+        return true; // local — ไม่ต้อง key
+    const k = resolveKeyFromEnv(cfg.envVar, cfg.envFallbacks);
+    if (!k)
+        return false;
+    try {
+        assertDirectApiKey(cfg, k); // reject OAuth prefix / format ผิด
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** หา provider ที่ "มี key ใช้ได้จริงใน env" (cloud, ตามลำดับนิยม) — ใช้ทำ first-run smart skip + แนะ headless */
+export function detectEnvProvider() {
+    for (const id of ['anthropic', 'openai', 'google', 'deepseek', 'xai', 'mistral', 'groq', 'glm', 'minimax']) {
+        const cfg = PROVIDERS[id];
+        if (cfg?.requiresKey && hasUsableEnvKey(id)) {
+            return { provider: id, label: cfg.label, envVar: cfg.envVar, model: cfg.models.default };
+        }
+    }
+    return null;
+}
+/**
+ * model ที่ "ถูก/เร็วกว่า" ในค่ายเดียวกับ spec (สำหรับงานกลไก เช่น summarize/compaction) —
+ * ใช้ key เดียวกัน ไม่ต้องตั้ง key ใหม่. ไม่มี fast tier → คืน spec เดิม (ทำงานได้แต่ไม่ประหยัด)
+ */
+export function fastSibling(spec) {
+    const { provider } = parseSpec(spec);
+    const cfg = PROVIDERS[provider];
+    if (!cfg)
+        return spec;
+    const fast = cfg.models.fast ?? cfg.models.flash ?? cfg.models.haiku ?? cfg.models.air;
+    return fast ? `${provider}:${fast}` : spec;
+}
 /** resolve spec → LanguageModel (throw ถ้าไม่มี key / provider ผิด / key เป็น OAuth) */
 export function resolveModel(spec) {
     const { provider, model } = parseSpec(spec);
@@ -226,7 +291,11 @@ export function resolveModel(spec) {
     if (cfg.requiresKey) {
         const found = resolveKeyFromEnv(cfg.envVar, cfg.envFallbacks);
         if (!found) {
-            throw new Error(`ต้องตั้ง ${cfg.envVar} ก่อนใช้ provider "${provider}" (BYOK — API key ตรงจาก console)`);
+            const url = consoleUrl(provider);
+            throw new Error(`ยังไม่มี API key ของ ${cfg.label} (${cfg.envVar})\n` +
+                (url ? `  • เอา key ที่: ${url}\n` : '') +
+                `  • ตั้ง: export ${cfg.envVar}="..."   ` +
+                `หรือรัน \`${BRAND.cliName}\` (ไม่ใส่ task) เพื่อ setup wizard`);
         }
         assertDirectApiKey(cfg, found); // reject OAuth/subscription token + format ผิด
         key = found;
@@ -239,3 +308,88 @@ export function resolveModel(spec) {
         (cfg.requiresKey ? cfg.baseURL : process.env[cfg.envVar] ?? cfg.baseURL);
     return cfg.create(key, baseURL)(model);
 }
+export const EMBEDDING_PROVIDERS = {
+    openai: {
+        envVar: 'OPENAI_API_KEY',
+        requiresKey: true,
+        defaultModel: 'text-embedding-3-small',
+        create: (key, baseURL) => (id) => createOpenAI({ apiKey: key, baseURL }).textEmbeddingModel(id),
+    },
+    mistral: {
+        envVar: 'MISTRAL_API_KEY',
+        requiresKey: true,
+        defaultModel: 'mistral-embed',
+        create: (key) => (id) => createMistral({ apiKey: key }).textEmbeddingModel(id),
+    },
+    google: {
+        envVar: 'GOOGLE_GENERATIVE_AI_API_KEY',
+        envFallbacks: ['GOOGLE_API_KEY', 'GEMINI_API_KEY'],
+        requiresKey: true,
+        defaultModel: 'text-embedding-004',
+        create: (key) => (id) => createGoogleGenerativeAI({ apiKey: key }).textEmbeddingModel(id),
+    },
+    // local — only picked when explicitly requested (auto-detect never assumes a server is up)
+    ollama: {
+        envVar: 'OLLAMA_BASE_URL',
+        requiresKey: false,
+        localPlaceholderKey: 'ollama',
+        defaultModel: 'nomic-embed-text',
+        create: (key, baseURL) => (id) => createOpenAICompatible({ name: 'ollama', apiKey: key, baseURL: baseURL ?? 'http://localhost:11434/v1' }).textEmbeddingModel(id),
+    },
+};
+/** cloud, key-gated providers tried (in order) when no explicit embeddingModel is configured. */
+const EMBED_AUTODETECT = ['openai', 'mistral', 'google'];
+function buildEmbedder(provider, modelId) {
+    const cfg = EMBEDDING_PROVIDERS[provider];
+    if (!cfg)
+        return null;
+    let key;
+    if (cfg.requiresKey) {
+        const found = resolveKeyFromEnv(cfg.envVar, cfg.envFallbacks);
+        if (!found)
+            return null;
+        const policy = PROVIDERS[provider];
+        if (policy) {
+            try {
+                assertDirectApiKey(policy, found);
+            }
+            catch {
+                return null;
+            }
+        }
+        key = found;
+    }
+    else {
+        key = resolveKeyFromEnv(cfg.envVar) ?? cfg.localPlaceholderKey ?? 'local';
+    }
+    const baseURL = process.env[`${provider.toUpperCase()}_BASE_URL`] ??
+        (cfg.requiresKey ? undefined : process.env[cfg.envVar] ?? undefined);
+    const id = modelId ?? cfg.defaultModel;
+    try {
+        return { model: cfg.create(key, baseURL)(id), provider, modelId: id, tag: `${provider}:${id}` };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve an embeddings model. `spec` is 'provider' | 'provider:modelId' | undefined.
+ * undefined → auto-detect the first cloud provider whose key is present. Returns null
+ * (never throws) when nothing resolves, so callers degrade to BM25-only.
+ */
+export function resolveEmbedder(spec) {
+    if (spec) {
+        const idx = spec.indexOf(':');
+        const provider = (idx === -1 ? spec : spec.slice(0, idx)).trim();
+        if (!provider)
+            return null;
+        const modelId = idx === -1 ? undefined : spec.slice(idx + 1).trim() || undefined;
+        return buildEmbedder(provider, modelId);
+    }
+    for (const provider of EMBED_AUTODETECT) {
+        const e = buildEmbedder(provider);
+        if (e)
+            return e;
+    }
+    return null;
+}

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;
+    }
+}