@zerowidth/workbench-sdk 2.0.0-alpha.0 → 2.1.1

package/src/integrations/sqlite.js

@@ -1,10 +1,11 @@
-import sqlite3 from 'sqlite3';
-import { promisify } from 'util';
+import { DatabaseSync } from 'node:sqlite';
 import path from 'path';
 import fs from 'fs';
 import { KnowledgeBaseInterface } from './knowledge-base-interface.js';
 
-// Import sqlite-vec extension
+// sqlite-vec ships a loadable extension (prebuilt per-platform .dylib/.so);
+// `getLoadablePath()` returns the binary we hand to node:sqlite's
+// `loadExtension`. No native node module / node-gyp build involved.
 import * as sqliteVec from 'sqlite-vec';
 
 export default class SQLiteIntegration extends KnowledgeBaseInterface {
@@ -21,48 +22,46 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
     }
 
     /**
-     * Initialize the database connection
+     * Initialize the database connection.
+     *
+     * Uses Node's built-in `node:sqlite` (DatabaseSync) — synchronous,
+     * zero native dependency, uniform across Node 22+/24 and Linux — rather
+     * than the legacy `sqlite3` native module. The public methods stay
+     * `async` for call-site compatibility.
      * @returns {Promise<void>}
      */
   async connect() {
     try {
-
-      
       // Check if database file exists
       if (!fs.existsSync(this.dbPath)) {
         throw new Error(`Database file not found: ${this.dbPath}`);
       }
 
-      // Create database connection
-      this.db = new sqlite3.Database(this.dbPath, (err) => {
-        if (err) {
-          throw new Error(`Failed to connect to database: ${err.message}`);
-        }
-      });
-
-            // Promisify the database methods
-            this.db.run = promisify(this.db.run.bind(this.db));
-            this.db.get = promisify(this.db.get.bind(this.db));
-            this.db.all = promisify(this.db.all.bind(this.db));
-            this.db.close = promisify(this.db.close.bind(this.db));
-
-            // Load sqlite-vec extension
-            try {
-                sqliteVec.load(this.db);
-            } catch (error) {
-                console.warn('[WARN] Failed to load sqlite-vec extension:', error.message);
-                // Don't fail the connection, just warn
-            }
-
-            // Test the connection
-            await this.db.get("SELECT 1");
-            this.isConnected = true;
+      // Open the connection with extension loading allowed so sqlite-vec
+      // can be attached.
+      this.db = new DatabaseSync(this.dbPath, { allowExtension: true });
 
-        } catch (error) {
-            this.isConnected = false;
-            throw new Error(`SQLite connection failed: ${error.message}`);
+      // Load sqlite-vec extension. Enable extension loading first where the
+      // runtime exposes the toggle (guarded for forward-compat).
+      try {
+        if (typeof this.db.enableLoadExtension === 'function') {
+          this.db.enableLoadExtension(true);
         }
+        this.db.loadExtension(sqliteVec.getLoadablePath());
+      } catch (error) {
+        console.warn('[WARN] Failed to load sqlite-vec extension:', error.message);
+        // Don't fail the connection, just warn — semanticSearch falls back
+        // to text search when vec functions are unavailable.
+      }
+
+      // Test the connection
+      this._get('SELECT 1');
+      this.isConnected = true;
+    } catch (error) {
+      this.isConnected = false;
+      throw new Error(`SQLite connection failed: ${error.message}`);
     }
+  }
 
   /**
    * Close the database connection and clean up temporary files
@@ -71,24 +70,35 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
   async disconnect() {
     if (this.db && this.isConnected) {
       try {
-        await this.db.close();
+        this.db.close();
         this.isConnected = false;
       } catch (error) {
         throw new Error(`Failed to close database: ${error.message}`);
       }
     }
-    
-    // Clean up temporary file if it exists
-    if (this.dbPath && (this.dbPath.includes('.temp') || this.dbPath.includes('knowledge_'))) {
-      try {
-        if (fs.existsSync(this.dbPath)) {
-          fs.unlinkSync(this.dbPath);
-        }
-      } catch (error) {
-        console.warn(`[WARN] Failed to cleanup temporary file ${this.dbPath}:`, error.message);
-        // Don't throw - cleanup should be best effort
-      }
-    }
+
+    // NOTE: disconnect() never deletes the database file. File lifecycle
+    // belongs to whoever created the file — the engine tracks and removes
+    // its own temp extractions (and hosts opt in via
+    // config.knowledgeBase.cleanupDbFiles); a path-substring heuristic
+    // here once deleted user-owned databases.
+  }
+
+  // ─── node:sqlite driver helpers ────────────────────────────────────────
+  // DatabaseSync is synchronous: prepare once, bind anonymous `?` params by
+  // spreading the params array. These wrap the three shapes the rest of the
+  // class needs.
+
+  _all(sql, params = []) {
+    return this.db.prepare(sql).all(...params);
+  }
+
+  _get(sql, params = []) {
+    return this.db.prepare(sql).get(...params);
+  }
+
+  _run(sql, params = []) {
+    return this.db.prepare(sql).run(...params);
   }
 
     /**
@@ -108,7 +118,7 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
             const allowedOperations = ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'CREATE', 'DROP', 'ALTER'];
             const queryUpper = query.trim().toUpperCase();
             const isAllowed = allowedOperations.some(op => queryUpper.startsWith(op));
-            
+
             if (!isAllowed) {
                 throw new Error(`Operation not allowed: ${queryUpper.split(' ')[0]}`);
             }
@@ -116,22 +126,30 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
             // Execute query based on operation type
             let result;
             if (operation.toUpperCase() === 'SELECT') {
-                if (queryUpper.includes('LIMIT 1')) {
-                    result = await this.db.get(query, params);
+                if (/\bLIMIT\s+1\b(?!\s*,)/.test(queryUpper)) {
+                    result = this._get(query, params);
                 } else {
-                    result = await this.db.all(query, params);
+                    result = this._all(query, params);
                 }
-            } else {
-                result = await this.db.run(query, params);
+                return {
+                    success: true,
+                    data: result,
+                    operation: operation.toUpperCase(),
+                    rowCount: Array.isArray(result) ? result.length : (result ? 1 : 0)
+                };
             }
 
+            // Non-SELECT: run() returns { changes, lastInsertRowid }.
+            const runResult = this._run(query, params);
             return {
                 success: true,
-                data: result,
+                data: {
+                    changes: Number(runResult.changes),
+                    lastID: runResult.lastInsertRowid,
+                },
                 operation: operation.toUpperCase(),
-                rowCount: result?.changes || (Array.isArray(result) ? result.length : 0)
+                rowCount: Number(runResult.changes) || 0
             };
-
         } catch (error) {
             throw new Error(`SQLite query failed: ${error.message}`);
         }
@@ -197,7 +215,7 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
      */
     async getSchema() {
         const tables = await this.select(`
-            SELECT name FROM sqlite_master 
+            SELECT name FROM sqlite_master
             WHERE type='table' AND name NOT LIKE 'sqlite_%'
             ORDER BY name
         `);
@@ -218,10 +236,10 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
     async validateKnowledgeBaseSchema() {
         try {
             const schema = await this.getSchema();
-            
+
             const hasDocuments = 'documents' in schema;
             const hasChunks = 'chunks' in schema;
-            
+
             if (!hasDocuments || !hasChunks) {
                 return {
                     valid: false,
@@ -267,7 +285,7 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
             const docCount = await this.select('SELECT COUNT(*) as count FROM documents');
             const chunkCount = await this.select('SELECT COUNT(*) as count FROM chunks');
             const totalSize = await this.select('SELECT SUM(file_size) as total_size FROM documents');
-            
+
             return {
                 documents: docCount[0]?.count || 0,
                 chunks: chunkCount[0]?.count || 0,
@@ -284,19 +302,29 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
      */
     async getEmbeddingModel() {
         try {
-            const recentChunk = await this.select(
+            const rows = await this.select(
                 'SELECT embedding_model FROM chunks WHERE embedding_model IS NOT NULL ORDER BY created_at DESC LIMIT 1'
             );
-            
-            if (recentChunk.length > 0 && recentChunk[0].embedding_model) {
-                return recentChunk[0].embedding_model;
+
+            // `select()` returns a single object for LIMIT-1 queries (query()
+            // dispatches those through `_get`), or an array otherwise —
+            // normalize to the first row. Reading `.length` on the object
+            // silently missed the stored model and fell through to the default,
+            // whose NON-namespaced value ("text-embedding-3-small") then never
+            // matched the namespaced model the chunks are indexed under
+            // ("openai/text-embedding-3-small"), so `WHERE embedding_model = ?`
+            // dropped every row.
+            const row = Array.isArray(rows) ? rows[0] : rows;
+            if (row && row.embedding_model) {
+                return row.embedding_model;
             }
-            
-            // Fall back to default
-            return 'text-embedding-3-small';
+
+            // Fall back to the namespaced default (matches the ingestion
+            // default + OpenRouter's expected model id).
+            return 'openai/text-embedding-3-small';
         } catch (error) {
             console.warn('[WARN] Failed to get embedding model from database, using default:', error.message);
-            return 'text-embedding-3-small';
+            return 'openai/text-embedding-3-small';
         }
     }
 
@@ -336,7 +364,7 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
 
             // Check if sqlite-vec extension is loaded
             try {
-                await this.db.get("SELECT vec_version()");
+                this._get("SELECT vec_version()");
             } catch (error) {
                 console.warn('[WARN] sqlite-vec extension not loaded properly, falling back to text search');
                 return await this._fallbackTextSearch(query, options);
@@ -351,10 +379,10 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
             const queryEmbedding = options.query_embedding;
             const embeddingDimensions = queryEmbedding.length;
             const queryEmbeddingString = JSON.stringify(queryEmbedding);
-            
+
             // Build the KNN query using sqlite-vec scalar functions
             let searchSql = `
-                SELECT 
+                SELECT
                     c.id,
                     c.document_id,
                     c.chunk_index,
@@ -375,10 +403,16 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
                 WHERE c.embedding IS NOT NULL
                     AND c.embedding_model = ?
                     AND c.embedding_dimensions = ?
-                    AND vec_distance_cosine(c.embedding, ?) >= ?
+                    AND vec_distance_cosine(c.embedding, ?) <= ?
             `;
 
-            const params = [queryEmbeddingString, modelToUse, embeddingDimensions, queryEmbeddingString, similarity_threshold];
+            // vec_distance_cosine is a DISTANCE (0 = identical, larger = less
+            // similar). Callers pass `similarity_threshold` in [0,1] (1 =
+            // identical), so convert: similarity >= t  ⟺  distance <= (1 - t).
+            // (Previously this compared distance `>= threshold`, which dropped
+            // the closest matches and kept the farthest — inverted.)
+            const maxDistance = 1 - similarity_threshold;
+            const params = [queryEmbeddingString, modelToUse, embeddingDimensions, queryEmbeddingString, maxDistance];
 
             // Add document filter if specified
             if (document_id) {
@@ -394,8 +428,8 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
             // Add the query embedding and limit to params
             params.push(queryEmbeddingString, limit);
 
-            const results = await this.db.all(searchSql, params);
-            
+            const results = this._all(searchSql, params);
+
             // Parse JSON metadata and format results
             return results.map(row => ({
                 id: row.id,
@@ -410,10 +444,12 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
                 metadata: row.metadata ? JSON.parse(row.metadata) : {},
                 embedding_model: row.embedding_model,
                 embedding_dimensions: row.embedding_dimensions,
-                similarity_score: row.similarity,
+                // `row.similarity` is the aliased cosine DISTANCE; report it as
+                // an actual similarity in [-1, 1] (1 = identical).
+                similarity_score: 1 - row.similarity,
                 created_at: row.created_at
             }));
-            
+
         } catch (error) {
             console.warn('[WARN] Vector search failed, falling back to text search:', error.message);
             return await this._fallbackTextSearch(query, options);
@@ -434,7 +470,7 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
 
         try {
             let sql = `
-                SELECT 
+                SELECT
                     c.id,
                     c.document_id,
                     c.chunk_index,
@@ -450,28 +486,444 @@ export default class SQLiteIntegration extends KnowledgeBaseInterface {
                 LEFT JOIN documents d ON c.document_id = d.id
                 WHERE c.content LIKE ?
             `;
-            
+
             const params = [`%${query}%`];
-            
+
             if (document_id) {
                 sql += ' AND c.document_id = ?';
                 params.push(document_id);
             }
-            
+
             sql += ' ORDER BY c.created_at DESC LIMIT ?';
             params.push(limit);
-            
+
             const results = await this.select(sql, params);
-            
+
             // Add mock similarity scores for text search
             return results.map((result, index) => ({
                 ...result,
                 similarity_score: 1.0 - (index * 0.1), // Mock decreasing similarity
                 match_type: 'text_search'
             }));
-            
+
         } catch (error) {
             throw new Error(`Fallback text search failed: ${error.message}`);
         }
     }
+
+    /**
+     * Keyword (substring) search over chunk content — the free, no-embedding
+     * complement to semanticSearch. Case-insensitive; ranks by number of
+     * occurrences (mirrors the in-app KB "test search" keyword mode). Returns
+     * the same row shape as semanticSearch (plus `match_count` / `match_type`).
+     * @param {string} query - Text to match within chunk content
+     * @param {Object} options - { limit = 10, document_id = null }
+     * @returns {Promise<Array>} Matching chunks, most matches first
+     */
+    async keywordSearch(query, options = {}) {
+        const { limit = 10, document_id = null } = options;
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        const q = String(query ?? '');
+        if (q.length === 0) return [];
+
+        let sql = `
+            SELECT
+                c.id,
+                c.document_id,
+                c.chunk_index,
+                c.content,
+                c.token_count,
+                c.chunk_type,
+                c.metadata,
+                c.embedding_model,
+                c.embedding_dimensions,
+                d.display_name as document_name,
+                d.file_type,
+                d.folder_path,
+                c.created_at
+            FROM chunks c
+            LEFT JOIN documents d ON c.document_id = d.id
+            WHERE c.content LIKE ? COLLATE NOCASE
+        `;
+        const params = [`%${q}%`];
+        if (document_id) {
+            sql += ' AND c.document_id = ?';
+            params.push(document_id);
+        }
+
+        // No SQL LIMIT: rank by occurrence count in JS, then slice.
+        const rows = this._all(sql, params);
+        const needle = q.toLowerCase();
+        const scored = rows.map((row) => {
+            const content = row.content ?? '';
+            const hay = content.toLowerCase();
+            let count = 0;
+            let idx = hay.indexOf(needle);
+            while (idx !== -1) {
+                count++;
+                idx = hay.indexOf(needle, idx + needle.length);
+            }
+            return {
+                ...row,
+                metadata: row.metadata ? JSON.parse(row.metadata) : {},
+                match_count: count,
+                match_type: 'keyword'
+            };
+        });
+        scored.sort((a, b) => b.match_count - a.match_count || a.chunk_index - b.chunk_index);
+        return scored.slice(0, limit);
+    }
+
+    /**
+     * List documents in the knowledge base (navigation, not search).
+     * @param {Object} options - { limit = 100, offset = 0 }
+     * @returns {Promise<Array>} Document rows with a chunk_count each
+     */
+    async listDocuments(options = {}) {
+        const { limit = 100, offset = 0 } = options;
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        return this._all(
+            `SELECT
+                d.id, d.display_name, d.file_type, d.file_size, d.folder_path,
+                d.created_at, d.updated_at,
+                (SELECT COUNT(*) FROM chunks c WHERE c.document_id = d.id) AS chunk_count
+             FROM documents d
+             ORDER BY d.created_at ASC, d.display_name ASC
+             LIMIT ? OFFSET ?`,
+            [limit, offset],
+        );
+    }
+
+    /**
+     * Read chunks of a document in order, starting at a chunk index — for
+     * pagination and "read what came after chunk N" (e.g. following a
+     * similarity hit). Returns chunks with index >= startIndex, ascending.
+     * @param {string} documentId
+     * @param {Object} options - { startIndex = 0, limit = 10 }
+     * @returns {Promise<Array>} Chunk rows (metadata parsed)
+     */
+    async getChunks(documentId, options = {}) {
+        const { startIndex = 0, limit = 10 } = options;
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        const rows = this._all(
+            `SELECT id, document_id, chunk_index, content, token_count, chunk_type, metadata, created_at
+             FROM chunks
+             WHERE document_id = ? AND chunk_index >= ?
+             ORDER BY chunk_index ASC
+             LIMIT ?`,
+            [documentId, startIndex, limit],
+        );
+        return rows.map((r) => ({
+            ...r,
+            metadata: r.metadata ? JSON.parse(r.metadata) : {},
+        }));
+    }
+
+    /**
+     * Read a window of chunks around a given chunk index — context expansion
+     * for a chunk found via search (grab the N before / after it).
+     * @param {string} documentId
+     * @param {number} chunkIndex - The anchor chunk's index
+     * @param {Object} options - { before = 1, after = 1 }
+     * @returns {Promise<Array>} Chunk rows in the window, ascending (metadata parsed)
+     */
+    async getChunkWindow(documentId, chunkIndex, options = {}) {
+        const { before = 1, after = 1 } = options;
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        const lo = Math.max(0, Number(chunkIndex) - before);
+        const hi = Number(chunkIndex) + after;
+        const rows = this._all(
+            `SELECT id, document_id, chunk_index, content, token_count, chunk_type, metadata, created_at
+             FROM chunks
+             WHERE document_id = ? AND chunk_index >= ? AND chunk_index <= ?
+             ORDER BY chunk_index ASC`,
+            [documentId, lo, hi],
+        );
+        return rows.map((r) => ({
+            ...r,
+            metadata: r.metadata ? JSON.parse(r.metadata) : {},
+        }));
+    }
+
+    /**
+     * Describe the tabular tables in a Tabular→SQL KB, from the `_kb_tables`
+     * registry — everything an LLM needs to write correct SQL: the column
+     * schema, a `CREATE TABLE` DDL (the format models expect), and a few
+     * sample rows (which disambiguate value formats / casing far better than
+     * types alone). Returns [] for a KB with no registry (e.g. a docs KB).
+     * @param {Object} options - { sampleLimit = 5 } rows per table (0 = none)
+     * @returns {Promise<Array>} [{ table_name, source_name, row_count, columns:[{name,type}], ddl, sample_rows }]
+     */
+    async listTables(options = {}) {
+        const { sampleLimit = 5 } = options;
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        let rows;
+        try {
+            rows = this._all(
+                `SELECT table_name, source_name, row_count, columns
+                 FROM _kb_tables
+                 ORDER BY table_name ASC`,
+            );
+        } catch {
+            return []; // no _kb_tables registry — not a tabular KB
+        }
+        return rows.map((r) => {
+            const tableName = String(r.table_name ?? "");
+            const columns = r.columns ? JSON.parse(r.columns) : [];
+            let sample_rows = [];
+            // Identifiers come from our own sanitizer, but guard the
+            // interpolation before it reaches SQL anyway.
+            if (sampleLimit > 0 && /^[a-zA-Z0-9_]+$/.test(tableName)) {
+                try {
+                    sample_rows = this._all(
+                        `SELECT * FROM "${tableName}" LIMIT ?`,
+                        [sampleLimit],
+                    );
+                } catch {
+                    sample_rows = [];
+                }
+            }
+            return {
+                table_name: r.table_name,
+                source_name: r.source_name,
+                row_count: r.row_count,
+                columns,
+                ddl: buildCreateTableDDL(tableName, columns),
+                sample_rows,
+            };
+        });
+    }
+
+    // ── Knowledge-graph traversal (Graph recipe, ADR 0023) ────────────
+    // Graph KBs carry `nodes` + `edges` tables (entities + typed
+    // relations, both with document provenance) alongside the same
+    // `_kb_tables` registry tabular uses — so `listTables` / `query`
+    // work on them unchanged; these methods add traversal sugar.
+    // Soft-fail convention matches listTables: a KB without graph
+    // tables returns empty shapes, never throws.
+
+    /**
+     * List entities, highest-degree first (degree = count of edges in
+     * either direction), so the "important" nodes surface first.
+     * @param {Object} options - { limit=100, offset=0, type=null, search=null }
+     * @returns {Promise<Array>} [{ id, name, type, description, document_id, degree, created_at }]
+     */
+    async listEntities(options = {}) {
+        const { limit = 100, offset = 0, type = null, search = null } = options;
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        try {
+            const where = [];
+            const params = [];
+            if (type) {
+                where.push("n.type = ? COLLATE NOCASE");
+                params.push(type);
+            }
+            if (search) {
+                where.push("n.name LIKE ? COLLATE NOCASE");
+                params.push(`%${search}%`);
+            }
+            return this._all(
+                `SELECT n.*, (
+                    SELECT COUNT(*) FROM edges e
+                    WHERE e.source_id = n.id OR e.target_id = n.id
+                 ) AS degree
+                 FROM nodes n
+                 ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
+                 ORDER BY degree DESC, n.name COLLATE NOCASE ASC
+                 LIMIT ? OFFSET ?`,
+                [...params, limit, offset],
+            );
+        } catch {
+            return []; // no nodes table — not a graph KB
+        }
+    }
+
+    /**
+     * Resolve an entity reference — exact id first, then
+     * case-insensitive name. Returns the node row or null.
+     */
+    async getEntity(ref) {
+        if (!this.isConnected) {
+            await this.connect();
+        }
+        if (typeof ref !== "string" || ref.length === 0) return null;
+        try {
+            return (
+                this._get(`SELECT * FROM nodes WHERE id = ?`, [ref]) ||
+                this._get(
+                    `SELECT * FROM nodes WHERE name = ? COLLATE NOCASE`,
+                    [ref],
+                ) ||
+                null
+            );
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Edges touching an entity, each joined with the node on the far
+     * side. `direction` filters to edges where the entity is the
+     * source ("out"), the target ("in"), or either ("both").
+     * @param {string} entityRef - entity id or (case-insensitive) name
+     * @param {Object} options - { direction="both", relation_type=null, limit=50 }
+     * @returns {Promise<Object>} { entity, neighbors: [{ edge_id, relation_type, description, direction, node }] }
+     */
+    async getNeighbors(entityRef, options = {}) {
+        const { direction = "both", relation_type = null, limit = 50 } = options;
+        const entity = await this.getEntity(entityRef);
+        if (!entity) return { entity: null, neighbors: [] };
+        try {
+            let directionSql;
+            if (direction === "out") directionSql = "e.source_id = ?";
+            else if (direction === "in") directionSql = "e.target_id = ?";
+            else directionSql = "(e.source_id = ? OR e.target_id = ?)";
+            const directionParams =
+                direction === "out" || direction === "in"
+                    ? [entity.id]
+                    : [entity.id, entity.id];
+            const typeSql = relation_type
+                ? " AND e.type = ? COLLATE NOCASE"
+                : "";
+            const rows = this._all(
+                `SELECT e.id AS edge_id, e.type AS relation_type,
+                        e.description, e.source_id, e.target_id,
+                        n.id AS node_id, n.name AS node_name,
+                        n.type AS node_type, n.description AS node_description
+                 FROM edges e
+                 JOIN nodes n ON n.id = CASE
+                    WHEN e.source_id = ? THEN e.target_id ELSE e.source_id
+                 END
+                 WHERE ${directionSql}${typeSql}
+                 LIMIT ?`,
+                [
+                    entity.id,
+                    ...directionParams,
+                    ...(relation_type ? [relation_type] : []),
+                    limit,
+                ],
+            );
+            return {
+                entity,
+                neighbors: rows.map((r) => ({
+                    edge_id: r.edge_id,
+                    relation_type: r.relation_type,
+                    description: r.description,
+                    direction: r.source_id === entity.id ? "out" : "in",
+                    node: {
+                        id: r.node_id,
+                        name: r.node_name,
+                        type: r.node_type,
+                        description: r.node_description,
+                    },
+                })),
+            };
+        } catch {
+            return { entity, neighbors: [] };
+        }
+    }
+
+    /**
+     * Shortest path between two entities — BFS over edges, direction-
+     * agnostic (relations read both ways for pathfinding). Edge count
+     * is capped so a runaway artifact can't wedge a run.
+     * @param {string} fromRef - entity id or (case-insensitive) name
+     * @param {string} toRef - entity id or (case-insensitive) name
+     * @param {Object} options - { max_depth=4, max_edges=50000 }
+     * @returns {Promise<Object>} { found, from, to, hops, steps: [{ node, via_edge? }] }
+     */
+    async findPath(fromRef, toRef, options = {}) {
+        const { max_depth = 4, max_edges = 50000 } = options;
+        const from = await this.getEntity(fromRef);
+        const to = await this.getEntity(toRef);
+        if (!from || !to) {
+            return { found: false, from, to, hops: 0, steps: [] };
+        }
+        if (from.id === to.id) {
+            return { found: true, from, to, hops: 0, steps: [{ node: from }] };
+        }
+        let edges;
+        try {
+            edges = this._all(
+                `SELECT id, source_id, target_id, type FROM edges LIMIT ?`,
+                [max_edges],
+            );
+        } catch {
+            return { found: false, from, to, hops: 0, steps: [] };
+        }
+        const adjacency = new Map();
+        for (const e of edges) {
+            if (!adjacency.has(e.source_id)) adjacency.set(e.source_id, []);
+            if (!adjacency.has(e.target_id)) adjacency.set(e.target_id, []);
+            adjacency.get(e.source_id).push({ next: e.target_id, edge: e });
+            adjacency.get(e.target_id).push({ next: e.source_id, edge: e });
+        }
+        // BFS with parent pointers.
+        const visited = new Map([[from.id, null]]);
+        let frontier = [from.id];
+        for (let depth = 0; depth < max_depth && frontier.length > 0; depth++) {
+            const next = [];
+            for (const nodeId of frontier) {
+                for (const { next: nextId, edge } of adjacency.get(nodeId) ?? []) {
+                    if (visited.has(nextId)) continue;
+                    visited.set(nextId, { prev: nodeId, edge });
+                    if (nextId === to.id) {
+                        return this._materializePath(from, to, visited);
+                    }
+                    next.push(nextId);
+                }
+            }
+            frontier = next;
+        }
+        return { found: false, from, to, hops: 0, steps: [] };
+    }
+
+    /** Walk parent pointers back from `to`, hydrating node rows. */
+    _materializePath(from, to, visited) {
+        const reversed = [];
+        let cursor = to.id;
+        while (cursor !== from.id) {
+            const link = visited.get(cursor);
+            reversed.push({ nodeId: cursor, edge: link.edge });
+            cursor = link.prev;
+        }
+        const steps = [{ node: from }];
+        for (const { nodeId, edge } of reversed.reverse()) {
+            const node =
+                this._get(`SELECT * FROM nodes WHERE id = ?`, [nodeId]) ?? {
+                    id: nodeId,
+                };
+            steps.push({
+                node,
+                via_edge: {
+                    id: edge.id,
+                    type: edge.type,
+                    source_id: edge.source_id,
+                    target_id: edge.target_id,
+                },
+            });
+        }
+        return { found: true, from, to, hops: steps.length - 1, steps };
+    }
+}
+
+/** A `CREATE TABLE` statement for a KB table's columns — the schema format
+ *  LLMs are trained on for text-to-SQL. */
+function buildCreateTableDDL(name, columns) {
+    const cols = (columns || [])
+        .map((c) => `  "${c.name}" ${c.type}`)
+        .join(",\n");
+    return `CREATE TABLE "${name}" (\n${cols}\n);`;
 }