@andespindola/brainlink 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/infrastructure/sqlite/graph-reader.js

@@ -10,111 +10,258 @@ const toGraphLink = (row) => ({
 });
 const normalizeAgentFilter = (agentId) => agentId ? sanitizeAgentId(agentId) : undefined;
 const toTitleKey = (title) => title.toLowerCase();
-export const createGraphReader = (database) => ({
-    listLinks: (agentId) => {
-        const normalizedAgentId = normalizeAgentFilter(agentId);
-        const agentFilter = normalizedAgentId ? 'WHERE source.agent_id = ?' : '';
-        const rows = database
-            .prepare(`
-          SELECT
-            source.agent_id AS agent_id,
-            source.title AS from_title,
-            source.path AS from_path,
-            COALESCE(target.title, links.to_title) AS to_title,
-            target.path AS to_path,
-            links.weight AS weight,
-            links.priority AS priority
-          FROM links
-          JOIN documents source ON source.id = links.from_document_id
-          LEFT JOIN documents target ON target.id = links.to_document_id
-          ${agentFilter}
-          ORDER BY source.title, links.weight DESC, to_title
-        `)
-            .all(...(normalizedAgentId ? [normalizedAgentId] : []));
-        return rows.map(toGraphLink);
-    },
-    listBacklinks: (title, agentId) => {
-        const normalizedAgentId = normalizeAgentFilter(agentId);
-        const agentFilter = normalizedAgentId ? 'AND source.agent_id = ?' : '';
-        const titleKey = toTitleKey(title);
-        const rows = database
-            .prepare(`
-          SELECT
-            source.agent_id AS agent_id,
-            source.title AS from_title,
-            source.path AS from_path,
-            COALESCE(target.title, links.to_title) AS to_title,
-            target.path AS to_path,
-            links.weight AS weight,
-            links.priority AS priority
-          FROM links
-          JOIN documents source ON source.id = links.from_document_id
-          LEFT JOIN documents target ON target.id = links.to_document_id
-          WHERE links.to_title_key = ?
-          ${agentFilter}
-          ORDER BY links.weight DESC, source.title
-        `)
-            .all(...(normalizedAgentId ? [titleKey, normalizedAgentId] : [titleKey]));
-        return rows.map(toGraphLink);
-    },
-    getGraph: (agentId) => {
-        const normalizedAgentId = normalizeAgentFilter(agentId);
-        const documentAgentFilter = normalizedAgentId ? 'WHERE agent_id = ?' : '';
-        const edgeAgentFilter = normalizedAgentId ? 'WHERE source.agent_id = ?' : '';
-        const nodeRows = database
-            .prepare(`
-          SELECT id, agent_id, title, path, content, tags_json
-          FROM documents
-          ${documentAgentFilter}
-          ORDER BY title
-        `)
-            .all(...(normalizedAgentId ? [normalizedAgentId] : []));
-        const edgeRows = database
-            .prepare(`
-          SELECT
-            links.from_document_id AS source,
-            links.to_document_id AS target,
-            links.to_title AS target_title,
-            links.weight AS weight,
-            links.priority AS priority
-          FROM links
-          JOIN documents source ON source.id = links.from_document_id
-          ${edgeAgentFilter}
-          ORDER BY links.from_document_id, links.weight DESC, links.to_title
-        `)
-            .all(...(normalizedAgentId ? [normalizedAgentId] : []));
-        const nodes = nodeRows.map((row) => ({
-            id: row.id,
-            agentId: row.agent_id,
-            title: row.title,
-            path: row.path,
-            content: row.content,
-            tags: JSON.parse(row.tags_json)
-        }));
-        const edges = edgeRows.map((row) => ({
-            source: row.source,
-            target: row.target,
-            targetTitle: row.target_title,
-            weight: row.weight,
-            priority: row.priority
-        }));
-        return {
-            nodes,
-            edges
-        };
-    },
-    listAgents: () => {
-        const rows = database
-            .prepare(`
-          SELECT agent_id AS id, count(*) AS document_count
-          FROM documents
-          GROUP BY agent_id
-          ORDER BY agent_id
-        `)
-            .all();
-        return rows.map((row) => ({
+const toFtsQuery = (query) => query
+    .toLowerCase()
+    .match(/[\p{L}\p{N}_-]+/gu)
+    ?.map((term) => `"${term.replaceAll('"', '""')}"*`)
+    .join(' OR ') ?? '';
+export const createGraphReader = (database) => (() => {
+    const listLinksStatement = database.prepare(`
+      SELECT
+        source.agent_id AS agent_id,
+        source.title AS from_title,
+        source.path AS from_path,
+        COALESCE(target.title, links.to_title) AS to_title,
+        target.path AS to_path,
+        links.weight AS weight,
+        links.priority AS priority
+      FROM links
+      JOIN documents source ON source.id = links.from_document_id
+      LEFT JOIN documents target ON target.id = links.to_document_id
+      ORDER BY source.title, links.weight DESC, to_title
+    `);
+    const listLinksByAgentStatement = database.prepare(`
+      SELECT
+        source.agent_id AS agent_id,
+        source.title AS from_title,
+        source.path AS from_path,
+        COALESCE(target.title, links.to_title) AS to_title,
+        target.path AS to_path,
+        links.weight AS weight,
+        links.priority AS priority
+      FROM links
+      JOIN documents source ON source.id = links.from_document_id
+      LEFT JOIN documents target ON target.id = links.to_document_id
+      WHERE source.agent_id = ?
+      ORDER BY source.title, links.weight DESC, to_title
+    `);
+    const listBacklinksStatement = database.prepare(`
+      SELECT
+        source.agent_id AS agent_id,
+        source.title AS from_title,
+        source.path AS from_path,
+        COALESCE(target.title, links.to_title) AS to_title,
+        target.path AS to_path,
+        links.weight AS weight,
+        links.priority AS priority
+      FROM links
+      JOIN documents source ON source.id = links.from_document_id
+      LEFT JOIN documents target ON target.id = links.to_document_id
+      WHERE links.to_title_key = ?
+      ORDER BY links.weight DESC, source.title
+    `);
+    const listBacklinksByAgentStatement = database.prepare(`
+      SELECT
+        source.agent_id AS agent_id,
+        source.title AS from_title,
+        source.path AS from_path,
+        COALESCE(target.title, links.to_title) AS to_title,
+        target.path AS to_path,
+        links.weight AS weight,
+        links.priority AS priority
+      FROM links
+      JOIN documents source ON source.id = links.from_document_id
+      LEFT JOIN documents target ON target.id = links.to_document_id
+      WHERE links.to_title_key = ? AND source.agent_id = ?
+      ORDER BY links.weight DESC, source.title
+    `);
+    const graphNodesStatement = database.prepare(`
+      SELECT id, agent_id, title, path, content, tags_json
+      FROM documents
+      ORDER BY title
+    `);
+    const graphNodesByAgentStatement = database.prepare(`
+      SELECT id, agent_id, title, path, content, tags_json
+      FROM documents
+      WHERE agent_id = ?
+      ORDER BY title
+    `);
+    const graphSummaryNodesStatement = database.prepare(`
+      SELECT id, agent_id, title, path, '' AS content, tags_json
+      FROM documents
+      ORDER BY title
+    `);
+    const graphSummaryNodesByAgentStatement = database.prepare(`
+      SELECT id, agent_id, title, path, '' AS content, tags_json
+      FROM documents
+      WHERE agent_id = ?
+      ORDER BY title
+    `);
+    const graphEdgesStatement = database.prepare(`
+      SELECT
+        links.from_document_id AS source,
+        links.to_document_id AS target,
+        links.to_title AS target_title,
+        links.weight AS weight,
+        links.priority AS priority
+      FROM links
+      JOIN documents source ON source.id = links.from_document_id
+      ORDER BY links.from_document_id, links.weight DESC, links.to_title
+    `);
+    const graphEdgesByAgentStatement = database.prepare(`
+      SELECT
+        links.from_document_id AS source,
+        links.to_document_id AS target,
+        links.to_title AS target_title,
+        links.weight AS weight,
+        links.priority AS priority
+      FROM links
+      JOIN documents source ON source.id = links.from_document_id
+      WHERE source.agent_id = ?
+      ORDER BY links.from_document_id, links.weight DESC, links.to_title
+    `);
+    const graphNodeByIdStatement = database.prepare(`
+      SELECT id, agent_id, title, path, content, tags_json
+      FROM documents
+      WHERE id = ?
+    `);
+    const graphNodeByIdAndAgentStatement = database.prepare(`
+      SELECT id, agent_id, title, path, content, tags_json
+      FROM documents
+      WHERE id = ? AND agent_id = ?
+    `);
+    const filterNodeIdsMetadataStatement = database.prepare(`
+      SELECT id
+      FROM documents
+      WHERE lower(title) LIKE ?
+         OR lower(path) LIKE ?
+         OR lower(tags_json) LIKE ?
+      ORDER BY title
+      LIMIT ?
+    `);
+    const filterNodeIdsMetadataByAgentStatement = database.prepare(`
+      SELECT id
+      FROM documents
+      WHERE agent_id = ?
+        AND (
+          lower(title) LIKE ?
+          OR lower(path) LIKE ?
+          OR lower(tags_json) LIKE ?
+        )
+      ORDER BY title
+      LIMIT ?
+    `);
+    const filterNodeIdsContentStatement = database.prepare(`
+      SELECT DISTINCT documents.id AS id
+      FROM chunks_fts
+      JOIN documents ON documents.id = chunks_fts.document_id
+      WHERE chunks_fts MATCH ?
+      LIMIT ?
+    `);
+    const filterNodeIdsContentByAgentStatement = database.prepare(`
+      SELECT DISTINCT documents.id AS id
+      FROM chunks_fts
+      JOIN documents ON documents.id = chunks_fts.document_id
+      WHERE chunks_fts MATCH ?
+        AND documents.agent_id = ?
+      LIMIT ?
+    `);
+    const listAgentsStatement = database.prepare(`
+      SELECT agent_id AS id, count(*) AS document_count
+      FROM documents
+      GROUP BY agent_id
+      ORDER BY agent_id
+    `);
+    return {
+        listLinks: (agentId) => {
+            const normalizedAgentId = normalizeAgentFilter(agentId);
+            const rows = (normalizedAgentId
+                ? listLinksByAgentStatement.all(normalizedAgentId)
+                : listLinksStatement.all());
+            return rows.map(toGraphLink);
+        },
+        listBacklinks: (title, agentId) => {
+            const normalizedAgentId = normalizeAgentFilter(agentId);
+            const titleKey = toTitleKey(title);
+            const rows = (normalizedAgentId
+                ? listBacklinksByAgentStatement.all(titleKey, normalizedAgentId)
+                : listBacklinksStatement.all(titleKey));
+            return rows.map(toGraphLink);
+        },
+        getGraph: (agentId) => {
+            const normalizedAgentId = normalizeAgentFilter(agentId);
+            const nodeRows = (normalizedAgentId
+                ? graphNodesByAgentStatement.all(normalizedAgentId)
+                : graphNodesStatement.all());
+            const edgeRows = (normalizedAgentId
+                ? graphEdgesByAgentStatement.all(normalizedAgentId)
+                : graphEdgesStatement.all());
+            return {
+                nodes: nodeRows.map(toGraphNode),
+                edges: edgeRows.map(toGraphEdge)
+            };
+        },
+        getGraphSummary: (agentId) => {
+            const normalizedAgentId = normalizeAgentFilter(agentId);
+            const nodeRows = (normalizedAgentId
+                ? graphSummaryNodesByAgentStatement.all(normalizedAgentId)
+                : graphSummaryNodesStatement.all());
+            const edgeRows = (normalizedAgentId
+                ? graphEdgesByAgentStatement.all(normalizedAgentId)
+                : graphEdgesStatement.all());
+            return {
+                nodes: nodeRows.map(toGraphNode),
+                edges: edgeRows.map(toGraphEdge)
+            };
+        },
+        getGraphNode: (id, agentId) => {
+            const normalizedAgentId = normalizeAgentFilter(agentId);
+            const row = (normalizedAgentId
+                ? graphNodeByIdAndAgentStatement.get(id, normalizedAgentId)
+                : graphNodeByIdStatement.get(id));
+            return row ? toGraphNode(row) : undefined;
+        },
+        searchGraphNodeIds: (query, limit, agentId) => {
+            const normalizedQuery = query.trim().toLowerCase();
+            if (!normalizedQuery || limit <= 0) {
+                return [];
+            }
+            const normalizedAgentId = normalizeAgentFilter(agentId);
+            const likeQuery = `%${normalizedQuery}%`;
+            const metadataRows = (normalizedAgentId
+                ? filterNodeIdsMetadataByAgentStatement.all(normalizedAgentId, likeQuery, likeQuery, likeQuery, limit)
+                : filterNodeIdsMetadataStatement.all(likeQuery, likeQuery, likeQuery, limit));
+            const ids = new Set(metadataRows.map((row) => row.id));
+            const remainingLimit = Math.max(limit - ids.size, 0);
+            if (remainingLimit > 0) {
+                const ftsQuery = toFtsQuery(normalizedQuery);
+                if (ftsQuery) {
+                    const contentRows = (normalizedAgentId
+                        ? filterNodeIdsContentByAgentStatement.all(ftsQuery, normalizedAgentId, remainingLimit)
+                        : filterNodeIdsContentStatement.all(ftsQuery, remainingLimit));
+                    contentRows.forEach((row) => ids.add(row.id));
+                }
+            }
+            return Array.from(ids).slice(0, limit);
+        },
+        listAgents: () => listAgentsStatement.all().map((row) => ({
             id: row.id,
             documentCount: row.document_count
-        }));
-    }
+        }))
+    };
+})();
+const toGraphNode = (row) => ({
+    id: row.id,
+    agentId: row.agent_id,
+    title: row.title,
+    path: row.path,
+    content: row.content,
+    tags: JSON.parse(row.tags_json)
+});
+const toGraphEdge = (row) => ({
+    source: row.source,
+    target: row.target,
+    targetTitle: row.target_title,
+    weight: row.weight,
+    priority: row.priority
 });

package/dist/infrastructure/sqlite/recovery.js

@@ -0,0 +1,83 @@
+import Database from 'better-sqlite3';
+import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+const sqliteCorruptionHints = [
+    'database disk image is malformed',
+    'file is not a database',
+    'database is corrupted',
+    'malformed database schema',
+    'sqlite quick_check failed'
+];
+const normalizeMessage = (error) => error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+const isSqliteCorruptionError = (error) => sqliteCorruptionHints.some((hint) => normalizeMessage(error).includes(hint));
+const safeUnlink = (path) => {
+    if (!existsSync(path)) {
+        return;
+    }
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Ignore best-effort cleanup failures.
+    }
+};
+const clearSidecars = (databasePath) => {
+    safeUnlink(`${databasePath}-wal`);
+    safeUnlink(`${databasePath}-shm`);
+};
+const assertQuickCheck = (database) => {
+    const rows = database.prepare('PRAGMA quick_check').all();
+    const first = rows[0]?.quick_check?.toLowerCase() ?? 'ok';
+    if (first !== 'ok') {
+        throw new Error(`sqlite quick_check failed: ${first}`);
+    }
+};
+const archiveCorruptedDatabase = (databasePath) => {
+    if (!existsSync(databasePath)) {
+        return;
+    }
+    const archivedPath = `${databasePath}.corrupt-${Date.now()}`;
+    renameSync(databasePath, archivedPath);
+};
+const restoreFromBackupOrReset = (databasePath, backupPath) => {
+    clearSidecars(databasePath);
+    archiveCorruptedDatabase(databasePath);
+    if (existsSync(backupPath)) {
+        copyFileSync(backupPath, databasePath);
+        clearSidecars(databasePath);
+        return;
+    }
+    rmSync(databasePath, { force: true });
+};
+const openCheckedDatabase = (databasePath) => {
+    const database = new Database(databasePath);
+    try {
+        assertQuickCheck(database);
+    }
+    catch (error) {
+        database.close();
+        throw error;
+    }
+    return database;
+};
+export const createRecoverySnapshot = (database, backupPath) => {
+    const backupDirectory = dirname(backupPath);
+    const tempBackupPath = `${backupPath}.tmp`;
+    mkdirSync(backupDirectory, { recursive: true });
+    rmSync(tempBackupPath, { force: true });
+    database.prepare('VACUUM INTO ?').run(tempBackupPath);
+    renameSync(tempBackupPath, backupPath);
+};
+export const openDatabaseWithRecovery = (databasePath, backupPath) => {
+    mkdirSync(dirname(databasePath), { recursive: true });
+    try {
+        return openCheckedDatabase(databasePath);
+    }
+    catch (error) {
+        if (!isSqliteCorruptionError(error)) {
+            throw error;
+        }
+        restoreFromBackupOrReset(databasePath, backupPath);
+        return openCheckedDatabase(databasePath);
+    }
+};

package/dist/infrastructure/sqlite/schema.js

@@ -1,4 +1,4 @@
-const schemaVersion = 5;
+const schemaVersion = 6;
 const requiredTableColumns = {
     documents: ['id', 'agent_id', 'title', 'path', 'content', 'tags_json', 'frontmatter_json', 'created_at', 'updated_at'],
     chunks: ['id', 'document_id', 'ordinal', 'content', 'token_count', 'embedding_provider', 'embedding_json'],
@@ -67,7 +67,9 @@ export const createSchema = (database) => {
     );
 
     CREATE INDEX IF NOT EXISTS idx_documents_agent_title ON documents(agent_id, title);
+    CREATE INDEX IF NOT EXISTS idx_documents_agent_id ON documents(agent_id, id);
     CREATE INDEX IF NOT EXISTS idx_chunks_document_ordinal ON chunks(document_id, ordinal);
+    CREATE INDEX IF NOT EXISTS idx_chunks_token_count ON chunks(token_count);
 
     CREATE TABLE IF NOT EXISTS embedding_buckets (
       bucket TEXT NOT NULL,
@@ -92,6 +94,7 @@ export const createSchema = (database) => {
 
     CREATE INDEX IF NOT EXISTS idx_links_to_document_id ON links(to_document_id);
     CREATE INDEX IF NOT EXISTS idx_links_to_title_key ON links(to_title_key);
+    CREATE INDEX IF NOT EXISTS idx_links_source_weight ON links(from_document_id, weight DESC, to_title);
 
     CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
       chunk_id UNINDEXED,

package/dist/infrastructure/sqlite/search-reader.js

@@ -51,25 +51,6 @@ const mergeHybridResults = (ftsResults, semanticResults, limit) => {
     return sortByScore(Array.from(rows.values())).slice(0, limit);
 };
 const placeholders = (count) => Array.from({ length: count }, () => '?').join(', ');
-const readAllSemanticRows = (database, normalizedAgentId) => {
-    const semanticAgentFilter = normalizedAgentId ? 'WHERE documents.agent_id = ?' : '';
-    return database
-        .prepare(`
-      SELECT
-        documents.id AS document_id,
-        documents.agent_id AS agent_id,
-        documents.title AS title,
-        documents.path AS path,
-        chunks.id AS chunk_id,
-        chunks.content AS content,
-        documents.tags_json AS tags_json,
-        chunks.embedding_json AS embedding_json
-      FROM chunks
-      JOIN documents ON documents.id = chunks.document_id
-      ${semanticAgentFilter}
-    `)
-        .all(...(normalizedAgentId ? [normalizedAgentId] : []));
-};
 const readBucketedSemanticRows = (database, normalizedAgentId, queryEmbedding, limit) => {
     const buckets = createEmbeddingBuckets(queryEmbedding);
     if (buckets.length === 0) {
@@ -100,57 +81,108 @@ const readBucketedSemanticRows = (database, normalizedAgentId, queryEmbedding, l
     `)
         .all(...params);
 };
-const readSemanticRows = (database, normalizedAgentId, queryEmbedding, limit) => {
-    const candidateLimit = Math.max(limit * 96, 768);
-    const bucketedRows = readBucketedSemanticRows(database, normalizedAgentId, queryEmbedding, candidateLimit);
-    return bucketedRows.length > 0 ? bucketedRows : readAllSemanticRows(database, normalizedAgentId);
-};
-export const createSearchReader = (database) => ({
-    search: (query, limit, agentId, mode = 'hybrid', queryEmbedding = []) => {
-        const normalizedQuery = query.trim();
-        if (!normalizedQuery || limit <= 0) {
-            return [];
-        }
-        const normalizedAgentId = normalizeAgentFilter(agentId);
-        const ftsQuery = toFtsQuery(query);
-        const expandedLimit = Math.max(limit * 4, 24);
-        const ftsAgentFilter = normalizedAgentId ? 'AND documents.agent_id = ?' : '';
-        const ftsParams = normalizedAgentId ? [ftsQuery, normalizedAgentId, expandedLimit] : [ftsQuery, expandedLimit];
-        const ftsRows = mode === 'semantic' || !ftsQuery
-            ? []
-            : database
-                .prepare(`
-                SELECT
-                  documents.id AS document_id,
-                  documents.agent_id AS agent_id,
-                  documents.title AS title,
-                  documents.path AS path,
-                  chunks_fts.chunk_id AS chunk_id,
-                  chunks_fts.content AS content,
-                  bm25(chunks_fts) * -1 AS score,
-                  documents.tags_json AS tags_json
-                FROM chunks_fts
-                JOIN documents ON documents.id = chunks_fts.document_id
-                WHERE chunks_fts MATCH ?
-                ${ftsAgentFilter}
-                ORDER BY bm25(chunks_fts)
-                LIMIT ?
-              `)
-                .all(...ftsParams);
-        const ftsResults = ftsRows.map((row, index) => toSearchResult(row, toTextScore(index, ftsRows.length), toTextScore(index, ftsRows.length), 0, 'fts'));
-        const semanticRows = mode === 'fts' || queryEmbedding.length === 0 ? [] : readSemanticRows(database, normalizedAgentId, queryEmbedding, expandedLimit);
-        const semanticResults = sortByScore(semanticRows
-            .map((row) => {
-            const semanticScore = Math.max(0, cosineSimilarity(queryEmbedding, parseJsonArray(row.embedding_json).filter((value) => typeof value === 'number')));
-            return toSearchResult(row, semanticScore, 0, semanticScore, 'semantic');
-        })
-            .filter((result) => result.semanticScore > 0)).slice(0, expandedLimit);
-        if (mode === 'fts') {
-            return ftsResults.slice(0, limit);
-        }
-        if (mode === 'semantic') {
-            return semanticResults.slice(0, limit);
+export const createSearchReader = (database) => (() => {
+    const ftsRowsStatement = database.prepare(`
+      SELECT
+        documents.id AS document_id,
+        documents.agent_id AS agent_id,
+        documents.title AS title,
+        documents.path AS path,
+        chunks_fts.chunk_id AS chunk_id,
+        chunks_fts.content AS content,
+        bm25(chunks_fts) * -1 AS score,
+        documents.tags_json AS tags_json
+      FROM chunks_fts
+      JOIN documents ON documents.id = chunks_fts.document_id
+      WHERE chunks_fts MATCH ?
+      ORDER BY bm25(chunks_fts)
+      LIMIT ?
+    `);
+    const ftsRowsByAgentStatement = database.prepare(`
+      SELECT
+        documents.id AS document_id,
+        documents.agent_id AS agent_id,
+        documents.title AS title,
+        documents.path AS path,
+        chunks_fts.chunk_id AS chunk_id,
+        chunks_fts.content AS content,
+        bm25(chunks_fts) * -1 AS score,
+        documents.tags_json AS tags_json
+      FROM chunks_fts
+      JOIN documents ON documents.id = chunks_fts.document_id
+      WHERE chunks_fts MATCH ?
+        AND documents.agent_id = ?
+      ORDER BY bm25(chunks_fts)
+      LIMIT ?
+    `);
+    const semanticRowsStatement = database.prepare(`
+      SELECT
+        documents.id AS document_id,
+        documents.agent_id AS agent_id,
+        documents.title AS title,
+        documents.path AS path,
+        chunks.id AS chunk_id,
+        chunks.content AS content,
+        documents.tags_json AS tags_json,
+        chunks.embedding_json AS embedding_json
+      FROM chunks
+      JOIN documents ON documents.id = chunks.document_id
+      ORDER BY chunks.token_count ASC, documents.title ASC
+      LIMIT ?
+    `);
+    const semanticRowsByAgentStatement = database.prepare(`
+      SELECT
+        documents.id AS document_id,
+        documents.agent_id AS agent_id,
+        documents.title AS title,
+        documents.path AS path,
+        chunks.id AS chunk_id,
+        chunks.content AS content,
+        documents.tags_json AS tags_json,
+        chunks.embedding_json AS embedding_json
+      FROM chunks
+      JOIN documents ON documents.id = chunks.document_id
+      WHERE documents.agent_id = ?
+      ORDER BY chunks.token_count ASC, documents.title ASC
+      LIMIT ?
+    `);
+    const readAllSemanticRowsForLimit = (normalizedAgentId, limit) => (normalizedAgentId
+        ? semanticRowsByAgentStatement.all(normalizedAgentId, limit)
+        : semanticRowsStatement.all(limit));
+    const readSemanticRows = (normalizedAgentId, queryEmbedding, limit) => {
+        const candidateLimit = Math.min(Math.max(limit * 96, 768), 12_000);
+        const bucketedRows = readBucketedSemanticRows(database, normalizedAgentId, queryEmbedding, candidateLimit);
+        return bucketedRows.length > 0 ? bucketedRows : readAllSemanticRowsForLimit(normalizedAgentId, candidateLimit);
+    };
+    return {
+        search: (query, limit, agentId, mode = 'hybrid', queryEmbedding = []) => {
+            const normalizedQuery = query.trim();
+            if (!normalizedQuery || limit <= 0) {
+                return [];
+            }
+            const normalizedAgentId = normalizeAgentFilter(agentId);
+            const ftsQuery = toFtsQuery(query);
+            const expandedLimit = Math.max(limit * 4, 24);
+            const ftsRows = mode === 'semantic' || !ftsQuery
+                ? []
+                : (normalizedAgentId
+                    ? ftsRowsByAgentStatement.all(ftsQuery, normalizedAgentId, expandedLimit)
+                    : ftsRowsStatement.all(ftsQuery, expandedLimit));
+            const ftsResults = ftsRows.map((row, index) => toSearchResult(row, toTextScore(index, ftsRows.length), toTextScore(index, ftsRows.length), 0, 'fts'));
+            const semanticRows = mode === 'fts' || queryEmbedding.length === 0 ? [] : readSemanticRows(normalizedAgentId, queryEmbedding, expandedLimit);
+            const semanticResults = sortByScore(semanticRows
+                .map((row) => {
+                const semanticScore = Math.max(0, cosineSimilarity(queryEmbedding, parseJsonArray(row.embedding_json).filter((value) => typeof value === 'number')));
+                return toSearchResult(row, semanticScore, 0, semanticScore, 'semantic');
+            })
+                .filter((result) => result.semanticScore > 0)).slice(0, expandedLimit);
+            if (mode === 'fts') {
+                return ftsResults.slice(0, limit);
+            }
+            if (mode === 'semantic') {
+                return semanticResults.slice(0, limit);
+            }
+            return mergeHybridResults(ftsResults, semanticResults, limit);
         }
-        return mergeHybridResults(ftsResults, semanticResults, limit);
-    }
-});
+    };
+})();