alvin-bot 4.20.2 → 4.22.0

package/dist/services/embeddings/index.js

@@ -0,0 +1,499 @@
+/**
+ * Embeddings Facade — provider-agnostic memory search.
+ *
+ * Manages the SQLite DB, picks an active provider via auto-detect, handles
+ * schema migrations on provider switch, and exposes the legacy public API
+ * (initEmbeddings, searchMemory, reindexMemory, getIndexStats) so callers
+ * outside this module don't need to know which backend is running.
+ *
+ * Provider tiers (auto-detected in this order, override via EMBEDDINGS_PROVIDER):
+ *   1. Gemini   (3072-dim, GOOGLE_API_KEY)        — free tier
+ *   2. OpenAI   (1536-dim, OPENAI_API_KEY)        — ~$0.02/1M tokens
+ *   3. Ollama   (768-dim default, local)          — free, private
+ *   4. FTS5     (BM25 keyword, no key needed)     — universal fallback
+ *
+ * Schema-mismatch handling: when meta.embedding_model differs from the active
+ * provider's name (e.g. user added GOOGLE_API_KEY after running on FTS5), we
+ * drop the previous provider's tables, clear file_mtimes, and initialise the
+ * new provider's schema. The next reindexMemory() call repopulates everything
+ * from disk. This is what makes the "user adds key later" flow seamless.
+ */
+import fs from "fs";
+import path from "path";
+import { resolve } from "path";
+import os from "os";
+import { createRequire } from "module";
+import { MEMORY_DIR, MEMORY_FILE, EMBEDDINGS_DB } from "../../paths.js";
+import { ASSETS_DIR, ASSETS_INDEX_MD } from "../../paths.js";
+import { detectProvider, parseProviderKey } from "./auto-detect.js";
+let SqliteClass = null;
+let sqliteLoadAttempted = false;
+let sqliteLoadError = null;
+const cjsRequire = createRequire(import.meta.url);
+function loadSqlite() {
+    if (sqliteLoadAttempted)
+        return SqliteClass;
+    sqliteLoadAttempted = true;
+    try {
+        SqliteClass = cjsRequire("better-sqlite3");
+        return SqliteClass;
+    }
+    catch (err) {
+        sqliteLoadError = err instanceof Error ? err : new Error(String(err));
+        console.warn("⚠️ better-sqlite3 native binary unavailable — embeddings disabled. " +
+            "Bot continues without semantic memory search. Fix: rebuild deps with " +
+            "`cd $(npm root -g)/alvin-bot && npm rebuild better-sqlite3` or reinstall " +
+            "alvin-bot. Underlying error: " +
+            sqliteLoadError.message);
+        return null;
+    }
+}
+// ── State ────────────────────────────────────────────────
+const HUB_MEMORY_DIR = resolve(os.homedir(), ".claude", "hub", "MEMORY");
+const SCHEMA_VERSION = "2"; // bumped from 1 when introducing multi-provider
+let dbInstance = null;
+let activeProvider = null;
+let initialised = false;
+let initInFlight = null;
+// ── DB lifecycle ────────────────────────────────────────
+function openDb() {
+    if (dbInstance)
+        return dbInstance;
+    const Database = loadSqlite();
+    if (!Database)
+        return null;
+    fs.mkdirSync(path.dirname(EMBEDDINGS_DB), { recursive: true });
+    dbInstance = new Database(EMBEDDINGS_DB);
+    dbInstance.pragma("journal_mode = WAL");
+    dbInstance.pragma("synchronous = NORMAL");
+    dbInstance.pragma("temp_store = MEMORY");
+    dbInstance.pragma("mmap_size = 268435456"); // 256 MB
+    // Shared tables — owned by the facade, not by any single provider.
+    dbInstance.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS file_mtimes (
+      source   TEXT PRIMARY KEY,
+      mtime_ms REAL NOT NULL
+    );
+  `);
+    return dbInstance;
+}
+export function closeEmbeddingsDb() {
+    if (dbInstance) {
+        dbInstance.close();
+        dbInstance = null;
+    }
+    activeProvider = null;
+    initialised = false;
+    initInFlight = null;
+}
+// ── Meta helpers ────────────────────────────────────────
+function getMeta(db, key) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+    return row?.value ?? null;
+}
+function setMeta(db, key, value) {
+    db.prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+}
+function clearAllProviderSchemas(db) {
+    // Drop both possible provider-owned tables. Defensive — covers any past
+    // schema regardless of which provider wrote it.
+    db.exec("DROP TABLE IF EXISTS entries; DROP TABLE IF EXISTS entries_fts;");
+    db.exec("DELETE FROM file_mtimes;");
+}
+// ── File mtime tracking ─────────────────────────────────
+function getFileMtimes(db) {
+    const rows = db.prepare("SELECT source, mtime_ms FROM file_mtimes").all();
+    const out = {};
+    for (const r of rows)
+        out[r.source] = r.mtime_ms;
+    return out;
+}
+function setFileMtime(db, source, mtimeMs) {
+    db.prepare("INSERT INTO file_mtimes (source, mtime_ms) VALUES (?, ?) ON CONFLICT(source) DO UPDATE SET mtime_ms = excluded.mtime_ms").run(source, mtimeMs);
+}
+// ── File discovery ──────────────────────────────────────
+const TEXT_EXTENSIONS = new Set([".md", ".html", ".txt", ".css", ".ts"]);
+function walkAssetDir(dir) {
+    const results = [];
+    function walk(currentDir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = resolve(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (entry.isFile()) {
+                if (currentDir === dir && (entry.name === "INDEX.json" || entry.name === "INDEX.md"))
+                    continue;
+                results.push({ name: entry.name, path: fullPath });
+            }
+        }
+    }
+    walk(dir);
+    return results;
+}
+function getIndexableFiles() {
+    const files = [];
+    if (fs.existsSync(MEMORY_FILE)) {
+        files.push({ path: MEMORY_FILE, relativePath: "MEMORY.md" });
+    }
+    if (fs.existsSync(MEMORY_DIR)) {
+        const entries = fs.readdirSync(MEMORY_DIR);
+        for (const entry of entries) {
+            if (entry.endsWith(".md") && !entry.startsWith(".")) {
+                files.push({
+                    path: resolve(MEMORY_DIR, entry),
+                    relativePath: `memory/${entry}`,
+                });
+            }
+        }
+    }
+    if (fs.existsSync(HUB_MEMORY_DIR)) {
+        try {
+            const entries = fs.readdirSync(HUB_MEMORY_DIR);
+            for (const entry of entries) {
+                if (entry.endsWith(".md") && !entry.startsWith(".")) {
+                    files.push({
+                        path: resolve(HUB_MEMORY_DIR, entry),
+                        relativePath: `hub/${entry}`,
+                    });
+                }
+            }
+        }
+        catch {
+            /* hub dir not available */
+        }
+    }
+    if (fs.existsSync(ASSETS_INDEX_MD)) {
+        files.push({ path: ASSETS_INDEX_MD, relativePath: "assets/INDEX.md" });
+    }
+    if (fs.existsSync(ASSETS_DIR)) {
+        for (const entry of walkAssetDir(ASSETS_DIR)) {
+            if (TEXT_EXTENSIONS.has(path.extname(entry.name))) {
+                files.push({
+                    path: entry.path,
+                    relativePath: `assets/${path.relative(ASSETS_DIR, entry.path)}`,
+                });
+            }
+        }
+    }
+    return files;
+}
+function getStaleFiles(db) {
+    const all = getIndexableFiles();
+    const known = getFileMtimes(db);
+    const stale = [];
+    for (const f of all) {
+        try {
+            const mtime = fs.statSync(f.path).mtimeMs;
+            if (!known[f.relativePath] || known[f.relativePath] < mtime) {
+                stale.push(f);
+            }
+        }
+        catch {
+            /* file disappeared */
+        }
+    }
+    return stale;
+}
+// ── Chunking ────────────────────────────────────────────
+function chunkMarkdown(content, source) {
+    const chunks = [];
+    const sections = content.split(/^(?=## )/gm);
+    for (let i = 0; i < sections.length; i++) {
+        const section = sections[i].trim();
+        if (!section || section.length < 20)
+            continue;
+        if (section.length > 1000) {
+            const paragraphs = section.split(/\n\n+/);
+            let cur = "";
+            let chunkIdx = 0;
+            for (const p of paragraphs) {
+                if (cur.length + p.length > 800 && cur.length > 100) {
+                    chunks.push({ id: `${source}:${i}:${chunkIdx}`, source, text: cur.trim() });
+                    cur = "";
+                    chunkIdx++;
+                }
+                cur += p + "\n\n";
+            }
+            if (cur.trim().length > 20) {
+                chunks.push({ id: `${source}:${i}:${chunkIdx}`, source, text: cur.trim() });
+            }
+        }
+        else {
+            chunks.push({ id: `${source}:${i}`, source, text: section });
+        }
+    }
+    return chunks;
+}
+// ── Provider sync ───────────────────────────────────────
+/**
+ * Ensure the DB schema matches the active provider. If the stored model name
+ * differs from the active provider's, wipe provider-owned tables + file_mtimes
+ * so the next reindex repopulates from disk against the new schema. Idempotent.
+ */
+function syncProviderSchema(db, provider) {
+    // Legacy v4.20 DBs only have meta.model (set by embeddings-migration.ts).
+    // Treat that as the previous embedding_model so we don't accidentally
+    // wipe a 49 MB vector store just because the meta key was renamed.
+    const storedModel = getMeta(db, "embedding_model") ?? getMeta(db, "model");
+    // Schema mismatch is detected by provider-name change ONLY. Bumping
+    // SCHEMA_VERSION alone must NOT trigger a drop — vector providers (Gemini,
+    // OpenAI, Ollama) all share the same `entries` table layout, so a refactor
+    // version bump shouldn't cost users a full re-embed against the API.
+    const switched = storedModel !== null && storedModel !== provider.name;
+    if (switched) {
+        clearAllProviderSchemas(db);
+    }
+    // Initialise the active provider's schema (idempotent — IF NOT EXISTS guards).
+    provider.initSchema(db);
+    setMeta(db, "embedding_model", provider.name);
+    setMeta(db, "embedding_dim", String(provider.dim));
+    setMeta(db, "embedding_tier", provider.tier);
+    setMeta(db, "schemaVersion", SCHEMA_VERSION);
+    return { switched, previous: storedModel };
+}
+// ── Internal init ───────────────────────────────────────
+async function ensureInit() {
+    if (initialised && dbInstance && activeProvider) {
+        return { db: dbInstance, provider: activeProvider };
+    }
+    if (initInFlight) {
+        await initInFlight;
+        return initialised && dbInstance && activeProvider
+            ? { db: dbInstance, provider: activeProvider }
+            : null;
+    }
+    initInFlight = (async () => {
+        const db = openDb();
+        if (!db)
+            return; // sqlite unavailable — leave initialised=false
+        const overrideKey = parseProviderKey(process.env.EMBEDDINGS_PROVIDER);
+        const provider = await detectProvider(overrideKey);
+        const sync = syncProviderSchema(db, provider);
+        if (sync.switched) {
+            console.log(`ℹ️ Memory provider changed: ${sync.previous ?? "none"} → ${provider.name} (${provider.tier}). Reindex on next access.`);
+        }
+        else {
+            // Quiet info log on first startup of a new install.
+            const total = provider.countEntries(db);
+            if (total === 0) {
+                console.log(`ℹ️ Memory provider: ${provider.name} (${provider.tier}). Initial index will run on first use.`);
+            }
+        }
+        activeProvider = provider;
+        initialised = true;
+    })();
+    try {
+        await initInFlight;
+    }
+    finally {
+        initInFlight = null;
+    }
+    return initialised && dbInstance && activeProvider
+        ? { db: dbInstance, provider: activeProvider }
+        : null;
+}
+// ── Public API ──────────────────────────────────────────
+export async function reindexMemory(force = false) {
+    const ctx = await ensureInit();
+    if (!ctx)
+        return { indexed: 0, total: 0 };
+    const { db, provider } = ctx;
+    const filesToIndex = force ? getIndexableFiles() : getStaleFiles(db);
+    if (filesToIndex.length === 0) {
+        return { indexed: 0, total: provider.countEntries(db) };
+    }
+    // Drop existing entries for these files (per-source DELETE).
+    provider.dropEntriesForSources(db, filesToIndex.map(f => f.relativePath));
+    // Chunk all files.
+    const allChunks = [];
+    const fileMtimeMap = [];
+    for (const file of filesToIndex) {
+        try {
+            const content = fs.readFileSync(file.path, "utf-8");
+            const chunks = chunkMarkdown(content, file.relativePath);
+            for (const c of chunks)
+                allChunks.push(c);
+            fileMtimeMap.push(file);
+        }
+        catch (err) {
+            console.error(`Failed to chunk ${file.relativePath}:`, err);
+        }
+    }
+    if (allChunks.length === 0) {
+        // No content to embed — but DO update mtimes so we don't re-walk these
+        // files every startup.
+        const updMtime = db.transaction((files) => {
+            for (const f of files) {
+                try {
+                    setFileMtime(db, f.relativePath, fs.statSync(f.path).mtimeMs);
+                }
+                catch {
+                    /* file vanished */
+                }
+            }
+        });
+        updMtime(fileMtimeMap);
+        return { indexed: 0, total: provider.countEntries(db) };
+    }
+    await provider.indexChunks(db, allChunks);
+    // Update mtimes for indexed files.
+    const updMtime = db.transaction((files) => {
+        for (const f of files) {
+            try {
+                setFileMtime(db, f.relativePath, fs.statSync(f.path).mtimeMs);
+            }
+            catch {
+                /* file vanished */
+            }
+        }
+    });
+    updMtime(fileMtimeMap);
+    setMeta(db, "lastReindex", String(Date.now()));
+    // For Ollama with unknown dim, set it now from the actual vector size.
+    if (provider.dim === 0) {
+        // Probe one entry; vector providers store as BLOB, FTS5 doesn't have one.
+        try {
+            const row = db.prepare("SELECT vector FROM entries LIMIT 1").get();
+            if (row?.vector) {
+                const detectedDim = row.vector.byteLength / 4;
+                setMeta(db, "embedding_dim", String(detectedDim));
+            }
+        }
+        catch {
+            /* not a vector provider */
+        }
+    }
+    return { indexed: allChunks.length, total: provider.countEntries(db) };
+}
+export async function searchMemory(query, topK = 5, minScore = 0.3) {
+    const ctx = await ensureInit();
+    if (!ctx)
+        return [];
+    const { db, provider } = ctx;
+    // Lazy first-time index if empty.
+    if (provider.countEntries(db) === 0) {
+        try {
+            await reindexMemory();
+        }
+        catch (err) {
+            // Reindex failure (e.g. API key missing for vector provider) — return
+            // empty so the caller can degrade gracefully.
+            console.log(`ℹ️ Memory search unavailable: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+        if (provider.countEntries(db) === 0)
+            return [];
+    }
+    try {
+        return await provider.search(db, query, topK, minScore);
+    }
+    catch (err) {
+        console.log(`ℹ️ Memory search failed (${provider.name}): ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+export async function initEmbeddings() {
+    const ctx = await ensureInit();
+    if (!ctx)
+        return; // sqlite unavailable — already warned in loadSqlite
+    const { db, provider } = ctx;
+    try {
+        const stale = getStaleFiles(db);
+        if (stale.length === 0 && provider.countEntries(db) > 0) {
+            return; // already up to date
+        }
+        const result = await reindexMemory();
+        if (result.indexed > 0) {
+            console.log(`🔍 Memory indexed: ${result.indexed} chunks via ${provider.name} (${result.total} total)`);
+        }
+    }
+    catch (err) {
+        // Don't crash the bot if reindexing fails (e.g. API down). Log INFO not
+        // WARN — bot keeps running, search just returns empty until conditions
+        // recover. Public users without keys hit the FTS5 path which never throws.
+        console.log(`ℹ️ Memory init deferred: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function getIndexStats() {
+    const stats = {
+        entries: 0,
+        files: 0,
+        lastReindex: 0,
+        sizeBytes: 0,
+        provider: "unavailable",
+        tier: "none",
+        dim: 0,
+    };
+    if (!loadSqlite())
+        return stats;
+    const db = openDb();
+    if (!db)
+        return stats;
+    try {
+        if (activeProvider) {
+            stats.entries = activeProvider.countEntries(db);
+            stats.provider = activeProvider.name;
+            stats.tier = activeProvider.tier;
+            stats.dim = activeProvider.dim;
+        }
+        else {
+            // Fall back to stored meta if init never ran.
+            stats.provider = getMeta(db, "embedding_model") ?? "unknown";
+            stats.tier = getMeta(db, "embedding_tier") ?? "unknown";
+            stats.dim = Number(getMeta(db, "embedding_dim") ?? 0);
+        }
+        stats.files = db.prepare("SELECT COUNT(*) AS c FROM file_mtimes").get().c;
+        const lr = getMeta(db, "lastReindex");
+        if (lr)
+            stats.lastReindex = Number(lr);
+        if (fs.existsSync(EMBEDDINGS_DB))
+            stats.sizeBytes = fs.statSync(EMBEDDINGS_DB).size;
+    }
+    catch {
+        /* DB not initialised or partial */
+    }
+    return stats;
+}
+export function getEmbeddingsBackendStatus() {
+    loadSqlite();
+    return { available: SqliteClass !== null, error: sqliteLoadError?.message ?? null };
+}
+/**
+ * Synchronous probe: does the SQLite memory store have at least one indexed
+ * entry, regardless of which provider wrote it? Used by the inject-mode
+ * resolver to decide between legacy plain-text and SQLite-backed search at
+ * system-prompt build time (which is sync).
+ *
+ * Cheap: opens the DB if needed (idempotent), runs a single COUNT on whichever
+ * provider table exists. Does NOT call out to embedding APIs.
+ */
+export function isSqliteMemoryReady() {
+    if (!loadSqlite())
+        return false;
+    const db = openDb();
+    if (!db)
+        return false;
+    for (const tbl of ["entries", "entries_fts"]) {
+        try {
+            const r = db.prepare(`SELECT COUNT(*) AS c FROM ${tbl}`).get();
+            if (r && r.c > 0)
+                return true;
+        }
+        catch {
+            /* table missing — try next */
+        }
+    }
+    return false;
+}

package/dist/services/embeddings/ollama.js

@@ -0,0 +1,78 @@
+/**
+ * Ollama Memory Provider — local, private, free embeddings via Ollama.
+ *
+ * Default model: nomic-embed-text (768-dim, ~270 MB pull).
+ * Alternatives via OLLAMA_EMBEDDING_MODEL: mxbai-embed-large (1024-dim),
+ * all-minilm (384-dim, fast), bge-large (1024-dim).
+ *
+ * Uses /api/embed (newer batched endpoint). Detects host via OLLAMA_HOST or
+ * OLLAMA_BASE_URL env, defaults to http://localhost:11434.
+ */
+import { VectorProviderBase } from "./vector-base.js";
+const DEFAULT_MODEL = "nomic-embed-text";
+const DEFAULT_HOST = "http://localhost:11434";
+// Hardcoded dims for common models — saves a probe call. Unknown models fall
+// through to dynamic detection on first embed().
+const KNOWN_DIMS = {
+    "nomic-embed-text": 768,
+    "mxbai-embed-large": 1024,
+    "all-minilm": 384,
+    "bge-large": 1024,
+    "bge-small-en-v1.5": 384,
+    "snowflake-arctic-embed": 1024,
+};
+function ollamaHost() {
+    return process.env.OLLAMA_HOST || process.env.OLLAMA_BASE_URL || DEFAULT_HOST;
+}
+function ollamaModel() {
+    return process.env.OLLAMA_EMBEDDING_MODEL || DEFAULT_MODEL;
+}
+export class OllamaProvider extends VectorProviderBase {
+    name;
+    dim;
+    tier = "vector-local";
+    constructor() {
+        super();
+        const model = ollamaModel();
+        // Strip any tag like `:latest` for the dim lookup.
+        const baseModel = model.split(":")[0];
+        this.name = `ollama:${model}`;
+        this.dim = KNOWN_DIMS[baseModel] ?? 0; // 0 means "discover dynamically on first embed"
+    }
+    async isAvailable() {
+        try {
+            const res = await fetch(`${ollamaHost()}/api/tags`, {
+                signal: AbortSignal.timeout(2000),
+            });
+            if (!res.ok)
+                return false;
+            const data = (await res.json());
+            const wanted = ollamaModel();
+            const wantedBase = wanted.split(":")[0];
+            // Match either the exact tag or the base name.
+            return Boolean(data.models?.some(m => m.name === wanted || m.name.startsWith(`${wantedBase}:`)));
+        }
+        catch {
+            return false;
+        }
+    }
+    async embed(texts) {
+        const res = await fetch(`${ollamaHost()}/api/embed`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ model: ollamaModel(), input: texts }),
+        });
+        if (!res.ok) {
+            throw new Error(`Ollama embed error: ${res.status} — ${await res.text()}`);
+        }
+        const data = (await res.json());
+        if (!Array.isArray(data.embeddings) || data.embeddings.length !== texts.length) {
+            throw new Error(`Ollama embed returned ${data.embeddings?.length ?? 0} vectors, expected ${texts.length}`);
+        }
+        return data.embeddings;
+    }
+    async embedQuery(text) {
+        const [v] = await this.embed([text]);
+        return v;
+    }
+}

package/dist/services/embeddings/openai.js

@@ -0,0 +1,49 @@
+/**
+ * OpenAI Memory Provider — text-embedding-3-small (1536-dim, $0.02/1M tokens).
+ *
+ * Most public users already have OPENAI_API_KEY set for the LLM, so this is a
+ * near-zero-friction upgrade from FTS5. Reasonably priced even at heavy use.
+ */
+import { config } from "../../config.js";
+import { VectorProviderBase } from "./vector-base.js";
+const MODEL = "text-embedding-3-small";
+const DIM = 1536;
+const BATCH_SIZE = 100;
+export class OpenAIProvider extends VectorProviderBase {
+    name = MODEL;
+    dim = DIM;
+    tier = "vector-cloud";
+    async isAvailable() {
+        return Boolean(config.apiKeys.openai);
+    }
+    async embed(texts) {
+        const apiKey = config.apiKeys.openai;
+        if (!apiKey)
+            throw new Error("OPENAI_API_KEY not configured");
+        const out = [];
+        for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+            const batch = texts.slice(i, i + BATCH_SIZE);
+            const res = await fetch("https://api.openai.com/v1/embeddings", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({ model: MODEL, input: batch }),
+            });
+            if (!res.ok) {
+                throw new Error(`OpenAI embeddings API error: ${res.status} — ${await res.text()}`);
+            }
+            const data = (await res.json());
+            // Sort by index to keep order stable across the batch.
+            data.data.sort((a, b) => a.index - b.index);
+            for (const e of data.data)
+                out.push(e.embedding);
+        }
+        return out;
+    }
+    async embedQuery(text) {
+        const [v] = await this.embed([text]);
+        return v;
+    }
+}

package/dist/services/embeddings/provider.js

@@ -0,0 +1,22 @@
+/**
+ * Memory Provider interface — abstracts vector + keyword backends.
+ *
+ * The embeddings service supports four providers (Gemini, OpenAI, Ollama, FTS5)
+ * behind a single facade. Vector providers (Gemini/OpenAI/Ollama) share an
+ * `entries` table with a Float32 BLOB column. The FTS5 provider uses an
+ * `entries_fts` virtual table for BM25 keyword ranking — no embeddings, no
+ * keys, no API calls. Universal zero-config fallback.
+ *
+ * Common to all providers:
+ *   meta(key, value)              — model name, dim, lastReindex, pending_reindex
+ *   file_mtimes(source, mtime_ms) — staleness tracking
+ *
+ * Provider-owned tables:
+ *   Vector providers → entries(id, source, text, vector BLOB, indexed_at)
+ *   FTS5 provider    → entries_fts(text, source UNINDEXED, id UNINDEXED) VIRTUAL
+ *
+ * When the active provider changes (e.g. user adds GOOGLE_API_KEY), the facade
+ * detects the schema mismatch via meta.embedding_model and triggers a clean
+ * reindex against the new provider's schema.
+ */
+export {};