codestrate 0.6.1 → 0.6.3

package/dist/store/sqlite.js

@@ -211,6 +211,66 @@ const MIGRATIONS = [
             `CREATE UNIQUE INDEX IF NOT EXISTS idx_graph_nodes_symbol ON graph_nodes(symbol_id)`,
         ],
     },
+    {
+        version: 6,
+        name: "graph-confidence-community",
+        sql: [
+            `ALTER TABLE graph_edges ADD COLUMN confidence TEXT NOT NULL DEFAULT 'EXTRACTED'`,
+            `ALTER TABLE graph_nodes ADD COLUMN community INTEGER DEFAULT NULL`,
+            `CREATE INDEX IF NOT EXISTS idx_graph_nodes_community ON graph_nodes(community)`,
+            `CREATE INDEX IF NOT EXISTS idx_graph_edges_confidence ON graph_edges(confidence)`,
+        ],
+    },
+    {
+        version: 7,
+        name: "graph-enhancements",
+        sql: [
+            // ── Provenance: track where edges were extracted from ──
+            `ALTER TABLE graph_edges ADD COLUMN provenance TEXT DEFAULT ''`,
+            // ── Trigram FTS for CJK support ──
+            `CREATE VIRTUAL TABLE IF NOT EXISTS nodes_trigram_fts USING fts5(
+        name, file, signature,
+        content='graph_nodes',
+        content_rowid='id',
+        tokenize='unicode61 tokenchars ''\\u4e00-\\u9fff\\u3040-\\u309f\\u30a0-\\u30ff\\uac00-\\ud7af'''
+      )`,
+            `CREATE TRIGGER IF NOT EXISTS nodes_trigram_fts_ai AFTER INSERT ON graph_nodes BEGIN
+        INSERT INTO nodes_trigram_fts(rowid, name, file, signature)
+        VALUES (NEW.id, NEW.name, NEW.file, NEW.signature);
+      END`,
+            `CREATE TRIGGER IF NOT EXISTS nodes_trigram_fts_ad AFTER DELETE ON graph_nodes BEGIN
+        INSERT INTO nodes_trigram_fts(nodes_trigram_fts, rowid, name, file, signature)
+        VALUES ('delete', OLD.id, OLD.name, OLD.file, OLD.signature);
+      END`,
+            `CREATE TRIGGER IF NOT EXISTS nodes_trigram_fts_au AFTER UPDATE ON graph_nodes BEGIN
+        INSERT INTO nodes_trigram_fts(nodes_trigram_fts, rowid, name, file, signature)
+        VALUES ('delete', OLD.id, OLD.name, OLD.file, OLD.signature);
+        INSERT INTO nodes_trigram_fts(rowid, name, file, signature)
+        VALUES (NEW.id, NEW.name, NEW.file, NEW.signature);
+      END`,
+            `INSERT OR IGNORE INTO nodes_trigram_fts(rowid, name, file, signature)
+       SELECT id, name, file, signature FROM graph_nodes`,
+            // ── name_segment_vocab: materialized camelCase/snake_case parts ──
+            `CREATE TABLE IF NOT EXISTS name_segment_vocab (
+        segment TEXT NOT NULL,
+        node_id INTEGER NOT NULL REFERENCES graph_nodes(id) ON DELETE CASCADE,
+        UNIQUE(segment, node_id)
+      )`,
+            `CREATE INDEX IF NOT EXISTS idx_segment_vocab_segment ON name_segment_vocab(segment)`,
+            `CREATE INDEX IF NOT EXISTS idx_segment_vocab_node ON name_segment_vocab(node_id)`,
+            // ── Session reflections table (work memory) ──
+            `CREATE TABLE IF NOT EXISTS session_reflections (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        goal TEXT NOT NULL,
+        task TEXT NOT NULL,
+        symbols TEXT DEFAULT '[]',
+        files TEXT DEFAULT '[]',
+        timestamp TEXT NOT NULL DEFAULT (datetime('now'))
+      )`,
+            `CREATE INDEX IF NOT EXISTS idx_reflections_session ON session_reflections(session_id)`,
+        ],
+    },
 ];
 export class SQLiteStore {
     db = null;
@@ -356,7 +416,8 @@ export class SQLiteStore {
     }
     clearSymbols() {
         this.ensureOpen();
-        this.db.exec("DELETE FROM symbols; DELETE FROM relations");
+        // Keep symbols + relations + graph in lockstep (single source of truth)
+        this.db.exec("DELETE FROM graph_edges; DELETE FROM graph_nodes; DELETE FROM symbols; DELETE FROM relations");
     }
     // ── Full-text search (SQLite-only, requires migration v4) ──
     // These methods use the FTS5 virtual table for fast symbol search.
@@ -423,10 +484,32 @@ export class SQLiteStore {
             const name = key.split(":")[1];
             nameToId.set(name, id);
         }
+        // Insert name segments for every node (camelCase/snake_case splitting)
+        const segmentInsert = this.db.prepare(`
+      INSERT OR IGNORE INTO name_segment_vocab (segment, node_id)
+      VALUES (?, ?)
+    `);
+        const segmentBatch = this.db.transaction((segments) => {
+            for (const { seg, nodeId } of segments) {
+                segmentInsert.run(seg, nodeId);
+            }
+        });
+        const segmentEntries = [];
+        for (const [key, id] of nodeIds) {
+            const name = key.split(":")[1];
+            // Split on camelCase boundaries and snake_case
+            const parts = name.split(/(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])|_|-/).filter(p => p.length >= 2);
+            for (const part of parts) {
+                segmentEntries.push({ seg: part.toLowerCase(), nodeId: id });
+            }
+            // Also add the full lowercase name as a segment for prefix matching
+            segmentEntries.push({ seg: name.toLowerCase(), nodeId: id });
+        }
+        segmentBatch(segmentEntries);
         // Insert edges from call/called_by/imports in symbols
         const insertEdge = this.db.prepare(`
-      INSERT OR IGNORE INTO graph_edges (source_node_id, target_node_id, kind)
-      VALUES (?, ?, ?)
+      INSERT OR IGNORE INTO graph_edges (source_node_id, target_node_id, kind, confidence, provenance)
+      VALUES (?, ?, ?, 'EXTRACTED', ?)
     `);
         const parseArr = (val) => {
             if (Array.isArray(val))
@@ -449,7 +532,7 @@ export class SQLiteStore {
                 for (const targetName of parseArr(sym.calls)) {
                     const targetId = nameToId.get(targetName);
                     if (targetId && targetId !== myNodeId) {
-                        insertEdge.run(myNodeId, targetId, "calls");
+                        insertEdge.run(myNodeId, targetId, "calls", `call in ${sym.file}:${sym.line}`);
                     }
                 }
             }
@@ -458,7 +541,7 @@ export class SQLiteStore {
                 const sourceId = nameToId.get(rel.source);
                 const targetId = nameToId.get(rel.target);
                 if (sourceId && targetId && sourceId !== targetId) {
-                    insertEdge.run(sourceId, targetId, rel.kind);
+                    insertEdge.run(sourceId, targetId, rel.kind, `relation ${rel.kind}`);
                 }
             }
         })();
@@ -478,54 +561,41 @@ export class SQLiteStore {
             signature: row.signature,
             line: row.line ?? undefined,
             column: row.column ?? undefined,
+            community: row.community ?? undefined,
         };
     }
-    /** Get edges for a graph node. */
+    /** Get edges for a graph node — single query with OR for direction="both". */
     getGraphEdges(nodeId, direction = "both", kind) {
         this.ensureOpen();
-        let query;
         const params = [];
-        if (direction === "incoming" || direction === "both") {
-            query = "SELECT id, source_node_id, target_node_id, kind, line, \"column\" FROM graph_edges WHERE target_node_id = ?";
+        let whereClause;
+        if (direction === "incoming") {
+            whereClause = "target_node_id = ?";
             params.push(nodeId);
         }
-        else {
-            query = "SELECT id, source_node_id, target_node_id, kind, line, \"column\" FROM graph_edges WHERE source_node_id = ?";
+        else if (direction === "outgoing") {
+            whereClause = "source_node_id = ?";
             params.push(nodeId);
         }
+        else {
+            // Single query with OR instead of two separate queries
+            whereClause = "(source_node_id = ? OR target_node_id = ?)";
+            params.push(nodeId, nodeId);
+        }
         if (kind) {
-            query += " AND kind = ?";
+            whereClause += " AND kind = ?";
             params.push(kind);
         }
-        const rows = this.db.prepare(query).all(...params);
-        let edges = rows.map(r => ({
+        const rows = this.db.prepare(`SELECT id, source_node_id, target_node_id, kind, line, "column", confidence FROM graph_edges WHERE ${whereClause}`).all(...params);
+        return rows.map(r => ({
             id: r.id,
             sourceNodeId: r.source_node_id,
             targetNodeId: r.target_node_id,
             kind: r.kind,
             line: r.line ?? undefined,
             column: r.column ?? undefined,
+            confidence: String(r.confidence ?? "EXTRACTED"),
         }));
-        // For "both", also query incoming edges
-        if (direction === "both") {
-            let incomingQuery = "SELECT id, source_node_id, target_node_id, kind, line, \"column\" FROM graph_edges WHERE source_node_id = ?";
-            if (kind)
-                incomingQuery += " AND kind = ?";
-            const incomingParams = [nodeId];
-            if (kind)
-                incomingParams.push(kind);
-            const incomingRows = this.db.prepare(incomingQuery).all(...incomingParams);
-            const incomingEdges = incomingRows.map(r => ({
-                id: r.id,
-                sourceNodeId: r.source_node_id,
-                targetNodeId: r.target_node_id,
-                kind: r.kind,
-                line: r.line ?? undefined,
-                column: r.column ?? undefined,
-            }));
-            edges = [...edges, ...incomingEdges];
-        }
-        return edges;
     }
     /** Search graph nodes by name (LIKE fallback). */
     searchGraphNodes(query, limit = 20) {
@@ -544,6 +614,7 @@ export class SQLiteStore {
             signature: r.signature,
             line: r.line ?? undefined,
             column: r.column ?? undefined,
+            community: r.community != null ? Number(r.community) : undefined,
         }));
     }
     /** Search graph nodes by name using FTS5. */
@@ -650,49 +721,64 @@ export class SQLiteStore {
             return [];
         }
     }
-    /** Find a path between two graph nodes using BFS. */
+    /** Find a path between two graph nodes using BFS — pre-loads all edges for O(1) traversal. */
     findGraphPath(fromNodeId, toNodeId, maxDepth = 5) {
         this.ensureOpen();
-        // BFS on graph_edges
+        // Pre-load all edges into adjacency maps (one query instead of N)
+        const outgoing = new Map();
+        const incoming = new Map();
+        const allEdges = this.db.prepare("SELECT * FROM graph_edges").all();
+        for (const e of allEdges) {
+            if (!outgoing.has(e.source_node_id))
+                outgoing.set(e.source_node_id, []);
+            outgoing.get(e.source_node_id).push(e);
+            if (!incoming.has(e.target_node_id))
+                incoming.set(e.target_node_id, []);
+            incoming.get(e.target_node_id).push(e);
+        }
+        // BFS with index pointer (O(1) dequeue)
         const visited = new Set();
         const parent = new Map();
         const queue = [fromNodeId];
+        let head = 0;
         visited.add(fromNodeId);
-        for (let depth = 0; queue.length > 0 && depth < maxDepth; depth++) {
-            const levelSize = queue.length;
+        for (let depth = 0; head < queue.length && depth < maxDepth; depth++) {
+            const levelSize = queue.length - head;
             for (let i = 0; i < levelSize; i++) {
-                const currentId = queue.shift();
+                const currentId = queue[head++];
                 if (currentId === toNodeId) {
                     // Reconstruct path
                     const path = [];
                     let nodeId = toNodeId;
                     while (parent.has(nodeId)) {
                         const p = parent.get(nodeId);
-                        path.unshift(p.edge);
+                        path.unshift({
+                            id: p.edge.id,
+                            sourceNodeId: p.edge.source_node_id,
+                            targetNodeId: p.edge.target_node_id,
+                            kind: p.edge.kind,
+                            line: p.edge.line ?? undefined,
+                            column: p.edge.column ?? undefined,
+                            confidence: String(p.edge.confidence ?? "EXTRACTED"),
+                        });
                         nodeId = p.parentId;
                     }
                     return path;
                 }
-                // Get outgoing edges from current node
-                const edges = this.db
-                    .prepare("SELECT * FROM graph_edges WHERE source_node_id = ?")
-                    .all(currentId);
-                for (const edge of edges) {
-                    if (!visited.has(edge.target_node_id)) {
-                        visited.add(edge.target_node_id);
-                        parent.set(edge.target_node_id, { parentId: currentId, edge });
-                        queue.push(edge.target_node_id);
+                for (const edge of outgoing.get(currentId) ?? []) {
+                    const nid = edge.target_node_id;
+                    if (!visited.has(nid)) {
+                        visited.add(nid);
+                        parent.set(nid, { parentId: currentId, edge });
+                        queue.push(nid);
                     }
                 }
-                // Get incoming edges
-                const inEdges = this.db
-                    .prepare("SELECT * FROM graph_edges WHERE target_node_id = ?")
-                    .all(currentId);
-                for (const edge of inEdges) {
-                    if (!visited.has(edge.source_node_id)) {
-                        visited.add(edge.source_node_id);
-                        parent.set(edge.source_node_id, { parentId: currentId, edge });
-                        queue.push(edge.source_node_id);
+                for (const edge of incoming.get(currentId) ?? []) {
+                    const nid = edge.source_node_id;
+                    if (!visited.has(nid)) {
+                        visited.add(nid);
+                        parent.set(nid, { parentId: currentId, edge });
+                        queue.push(nid);
                     }
                 }
             }
@@ -704,6 +790,34 @@ export class SQLiteStore {
         this.ensureOpen();
         this.db.prepare("DELETE FROM graph_nodes WHERE file = ?").run(file);
     }
+    /**
+     * Find test files related to a source file by naming convention.
+     * Tests are found by matching `<name>.test.<ext>`, `<name>.spec.<ext>`,
+     * or `test/<name>.<ext>` patterns against the source file's basename.
+     */
+    findRelatedTests(filePath) {
+        this.ensureOpen();
+        const basename = filePath.split("/").pop()?.split(".")[0] ?? "";
+        if (!basename)
+            return [];
+        const rows = this.db
+            .prepare(`SELECT DISTINCT name FROM symbols
+         WHERE (file LIKE ? OR file LIKE ? OR file LIKE ?)
+         AND (file LIKE '%.test.%' OR file LIKE '%.spec.%' OR file LIKE '%/test/%')`)
+            .all(`%${basename}%`, `%${basename}.test.%`, `%${basename}.spec.%`);
+        return rows.map(r => r.name);
+    }
+    /**
+     * Find files in a scope (directory prefix match).
+     */
+    findFilesInScope(scope) {
+        this.ensureOpen();
+        const dirPrefix = scope.endsWith("/") ? scope : `${scope}/`;
+        const rows = this.db
+            .prepare("SELECT DISTINCT file FROM symbols WHERE file LIKE ?")
+            .all(`${dirPrefix}%`);
+        return rows.map(r => r.file);
+    }
     /** Clear all graph data. */
     clearGraph() {
         this.ensureOpen();
@@ -1015,6 +1129,542 @@ export class SQLiteStore {
             source: row.source,
         };
     }
+    // ── Graph traversal (BFS) ─────────────────────────────
+    /**
+     * Look up a graph node by name.
+     * Returns the first matching node if multiple exist.
+     */
+    getGraphNodeByName(name) {
+        this.ensureOpen();
+        const row = this.db
+            .prepare("SELECT * FROM graph_nodes WHERE name = ? LIMIT 1")
+            .get(name);
+        if (!row)
+            return null;
+        return {
+            id: Number(row.id),
+            symbolId: row.symbol_id ? Number(row.symbol_id) : undefined,
+            file: String(row.file ?? ""),
+            name: String(row.name ?? ""),
+            kind: String(row.kind ?? ""),
+            signature: String(row.signature ?? ""),
+            line: row.line ? Number(row.line) : undefined,
+            column: row.column ? Number(row.column) : undefined,
+            community: row.community ? Number(row.community) : undefined,
+        };
+    }
+    /**
+     * BFS traversal from a named graph node using a recursive CTE.
+     * Returns a SubgraphResult with all reachable nodes, edges, and stats.
+     *
+     * The recursive CTE handles cycle detection via a visited-set path column,
+     * so a diamond pattern is traversed exactly once per node.
+     */
+    traverseBFS(nodeName, opts) {
+        this.ensureOpen();
+        const maxDepth = opts?.maxDepth ?? 5;
+        const limit = opts?.limit ?? 100;
+        const direction = opts?.direction ?? "outgoing";
+        const edgeKinds = opts?.edgeKinds;
+        const nodeKinds = opts?.nodeKinds;
+        // First, resolve the start node
+        const startNode = this.getGraphNodeByName(nodeName);
+        if (!startNode) {
+            return { nodes: [], edges: [], stats: { depth: 0, nodeCount: 0, edgeCount: 0, truncated: false } };
+        }
+        // Build edge direction condition for the CTE
+        // Note: recursive term uses "bfs" alias, not "n"
+        let edgeJoin;
+        let nextIdExpr;
+        if (direction === "incoming") {
+            edgeJoin = "graph_edges e ON e.target_node_id = bfs.id";
+            nextIdExpr = "e.source_node_id";
+        }
+        else if (direction === "both") {
+            edgeJoin = "graph_edges e ON (e.source_node_id = bfs.id OR e.target_node_id = bfs.id)";
+            nextIdExpr = "CASE WHEN e.source_node_id = bfs.id THEN e.target_node_id ELSE e.source_node_id END";
+        }
+        else {
+            // outgoing (default)
+            edgeJoin = "graph_edges e ON e.source_node_id = bfs.id";
+            nextIdExpr = "e.target_node_id";
+        }
+        let kindFilter = "";
+        const params = [startNode.id, maxDepth];
+        if (edgeKinds && edgeKinds.length > 0) {
+            kindFilter = ` AND e.kind IN (${edgeKinds.map(() => "?").join(",")})`;
+            params.push(...edgeKinds);
+        }
+        params.push(limit);
+        // Recursive CTE for BFS
+        const cte = `
+      WITH RECURSIVE bfs AS (
+        -- Anchor: start node at depth 0
+        SELECT n.id, n.name, n.kind, n.file, n.signature, n.line, n."column",
+               n.symbol_id, 0 AS depth,
+               ',' || CAST(n.id AS TEXT) || ',' AS visited_path
+        FROM graph_nodes n
+        WHERE n.id = ?
+
+        UNION ALL
+
+        -- Recursive: follow edges to unvisited nodes
+        SELECT gn.id, gn.name, gn.kind, gn.file, gn.signature,
+               gn.line, gn."column", gn.symbol_id,
+               bfs.depth + 1,
+               bfs.visited_path || CAST(gn.id AS TEXT) || ','
+        FROM bfs
+        JOIN ${edgeJoin}
+        JOIN graph_nodes gn ON gn.id = ${nextIdExpr}
+        WHERE bfs.depth < ?
+          AND instr(bfs.visited_path, ',' || CAST(gn.id AS TEXT) || ',') = 0
+          ${kindFilter}
+      )
+      SELECT DISTINCT id, name, kind, file, signature, line, "column", symbol_id, depth
+      FROM bfs
+      ORDER BY depth, name
+      LIMIT ?
+    `;
+        const nodeRows = this.db.prepare(cte).all(...params);
+        // Build depth map for O(1) lookup (avoid O(n²) .find() in stats)
+        const depthMap = new Map();
+        for (const r of nodeRows) {
+            depthMap.set(Number(r.id), Number(r.depth));
+        }
+        const nodes = nodeRows.map(r => ({
+            id: Number(r.id),
+            name: String(r.name ?? ""),
+            kind: String(r.kind ?? ""),
+            file: String(r.file ?? ""),
+            signature: String(r.signature ?? ""),
+            line: r.line ? Number(r.line) : undefined,
+            column: r.column ? Number(r.column) : undefined,
+            symbolId: r.symbol_id ? Number(r.symbol_id) : undefined,
+        }));
+        const nodeIds = nodes.map(n => n.id);
+        const truncated = nodes.length >= limit;
+        // Fetch all edges between the returned nodes
+        let edges = [];
+        if (nodeIds.length > 0) {
+            const placeholders = nodeIds.map(() => "?").join(",");
+            let edgeQuery = `
+        SELECT id, source_node_id, target_node_id, kind, line, "column", confidence
+        FROM graph_edges
+        WHERE source_node_id IN (${placeholders}) AND target_node_id IN (${placeholders})
+      `;
+            let edgeParams = [...nodeIds, ...nodeIds];
+            if (edgeKinds && edgeKinds.length > 0) {
+                edgeQuery += ` AND kind IN (${edgeKinds.map(() => "?").join(",")})`;
+                edgeParams = [...edgeParams, ...edgeKinds];
+            }
+            const edgeRows = this.db.prepare(edgeQuery).all(...edgeParams);
+            edges = edgeRows.map(r => ({
+                id: Number(r.id),
+                sourceNodeId: Number(r.source_node_id),
+                targetNodeId: Number(r.target_node_id),
+                kind: String(r.kind ?? ""),
+                line: r.line ? Number(r.line) : undefined,
+                column: r.column ? Number(r.column) : undefined,
+                confidence: String(r.confidence ?? "EXTRACTED"),
+            }));
+        }
+        // Apply nodeKind filter post-CTE (since recursive CTE can't filter by code)
+        let filteredNodes = nodes;
+        if (nodeKinds && nodeKinds.length > 0) {
+            const nodeKindSet = new Set(nodeKinds);
+            filteredNodes = nodes.filter(n => nodeKindSet.has(n.kind));
+            if (filteredNodes.length === 0) {
+                return { nodes: [], edges: [], stats: { depth: 0, nodeCount: 0, edgeCount: 0, truncated: false } };
+            }
+            const filteredIds = new Set(filteredNodes.map(n => n.id));
+            edges = edges.filter(e => filteredIds.has(e.sourceNodeId) && filteredIds.has(e.targetNodeId));
+        }
+        return {
+            nodes: filteredNodes,
+            edges,
+            stats: {
+                depth: Math.min(maxDepth, Math.max(...filteredNodes.map(n => depthMap.get(n.id) ?? 0), 0)),
+                nodeCount: filteredNodes.length,
+                edgeCount: edges.length,
+                truncated,
+            },
+        };
+    }
+    /**
+     * Find the shortest directed path between two named graph nodes.
+     * Uses a bidirectional BFS strategy: a recursive CTE anchored at the start
+     * searches for the end node, tracking paths.
+     *
+     * Returns the sequence of edges forming the path, or null if unreachable.
+     */
+    traverseBFSCallPath(startNode, endNode, opts) {
+        this.ensureOpen();
+        const maxDepth = opts?.maxDepth ?? 10;
+        const direction = opts?.direction ?? "outgoing";
+        const start = this.getGraphNodeByName(startNode);
+        const end = this.getGraphNodeByName(endNode);
+        if (!start || !end)
+            return null;
+        if (start.id === end.id)
+            return [];
+        // Build direction condition
+        // Note: recursive term uses "ps" alias, not "n"
+        let nextIdExpr;
+        let joinOnEnd;
+        if (direction === "incoming") {
+            nextIdExpr = "e.source_node_id";
+            joinOnEnd = "graph_edges e ON e.target_node_id = ps.id";
+        }
+        else if (direction === "both") {
+            nextIdExpr = "CASE WHEN e.source_node_id = ps.id THEN e.target_node_id ELSE e.source_node_id END";
+            joinOnEnd = "graph_edges e ON (e.source_node_id = ps.id OR e.target_node_id = ps.id)";
+        }
+        else {
+            nextIdExpr = "e.target_node_id";
+            joinOnEnd = "graph_edges e ON e.source_node_id = ps.id";
+        }
+        const cte = `
+      WITH RECURSIVE path_search AS (
+        SELECT n.id,
+               ',' || CAST(n.id AS TEXT) || ',' AS path_ids,
+               '' AS edge_ids
+        FROM graph_nodes n WHERE n.id = ?
+
+        UNION ALL
+
+        SELECT gn.id,
+               ps.path_ids || CAST(gn.id AS TEXT) || ',',
+               ps.edge_ids || CAST(e.id AS TEXT) || ','
+        FROM path_search ps
+        JOIN ${joinOnEnd}
+        JOIN graph_nodes gn ON gn.id = ${nextIdExpr}
+        WHERE ps.id != ?
+          AND instr(ps.path_ids, ',' || CAST(gn.id AS TEXT) || ',') = 0
+          AND length(ps.path_ids) - length(replace(ps.path_ids, ',', '')) < ?
+      )
+      SELECT edge_ids FROM path_search
+      WHERE instr(path_ids, ',' || CAST(? AS TEXT) || ',') > 0
+      ORDER BY length(path_ids) - length(replace(path_ids, ',', '')) ASC
+      LIMIT 1
+    `;
+        const row = this.db.prepare(cte).get(start.id, end.id, maxDepth, end.id);
+        if (!row)
+            return null;
+        const edgeIdStr = String(row.edge_ids ?? "");
+        if (!edgeIdStr)
+            return [];
+        const edgeIds = edgeIdStr.split(",").filter(Boolean).map(Number);
+        if (edgeIds.length === 0)
+            return [];
+        // Fetch edges in path order
+        const placeholders = edgeIds.map(() => "?").join(",");
+        const edgeRows = this.db
+            .prepare(`SELECT id, source_node_id, target_node_id, kind, line, "column", confidence FROM graph_edges WHERE id IN (${placeholders})`)
+            .all(...edgeIds);
+        const edgeMap = new Map();
+        for (const r of edgeRows) {
+            const e = {
+                id: Number(r.id),
+                sourceNodeId: Number(r.source_node_id),
+                targetNodeId: Number(r.target_node_id),
+                kind: String(r.kind ?? ""),
+                line: r.line ? Number(r.line) : undefined,
+                column: r.column ? Number(r.column) : undefined,
+                confidence: String(r.confidence ?? "EXTRACTED"),
+            };
+            edgeMap.set(e.id, e);
+        }
+        return edgeIds.map(id => edgeMap.get(id)).filter((e) => e !== undefined);
+    }
+    // ── Graph analysis ──────────────────────────────────
+    /**
+     * Assign community IDs to graph nodes via connected-components analysis.
+     * Uses Union-Find (DSU) with path compression, O(n α(n)) time.
+     * Each connected component gets the minimum node ID as its community value.
+     * Returns the number of communities found.
+     */
+    computeCommunities() {
+        this.ensureOpen();
+        // Load all nodes and edges
+        const nodeIds = this.db.prepare("SELECT id FROM graph_nodes").all().map(r => r.id);
+        const edges = this.db.prepare("SELECT source_node_id, target_node_id FROM graph_edges").all();
+        // Union-Find (DSU) with path compression + union by rank
+        const parent = new Map();
+        const rank = new Map();
+        function find(x) {
+            let p = parent.get(x);
+            if (p === undefined || p === x)
+                return x;
+            // Path compression
+            const root = find(p);
+            parent.set(x, root);
+            return root;
+        }
+        function union(a, b) {
+            const ra = find(a);
+            const rb = find(b);
+            if (ra === rb)
+                return;
+            // Union by rank — attach smaller tree under larger
+            const raRank = rank.get(ra) ?? 0;
+            const rbRank = rank.get(rb) ?? 0;
+            if (raRank < rbRank) {
+                parent.set(ra, rb);
+            }
+            else if (raRank > rbRank) {
+                parent.set(rb, ra);
+            }
+            else {
+                parent.set(rb, ra);
+                rank.set(ra, (rank.get(ra) ?? 0) + 1);
+            }
+        }
+        // Initialize each node as its own parent
+        for (const id of nodeIds) {
+            parent.set(id, id);
+            rank.set(id, 0);
+        }
+        // Union each edge
+        for (const edge of edges) {
+            union(edge.source_node_id, edge.target_node_id);
+        }
+        // Assign community = minimum node ID in each component
+        const rootToMin = new Map();
+        for (const id of nodeIds) {
+            const root = find(id);
+            const cur = rootToMin.get(root);
+            if (cur === undefined || id < cur) {
+                rootToMin.set(root, id);
+            }
+        }
+        // Build assignment: nodeId → communityId
+        const assignment = new Map();
+        for (const id of nodeIds) {
+            const root = find(id);
+            assignment.set(id, rootToMin.get(root));
+        }
+        // Write communities to DB in a transaction
+        const updateCommunity = this.db.prepare("UPDATE graph_nodes SET community = ? WHERE id = ?");
+        this.db.transaction(() => {
+            // Reset first
+            this.db.exec("UPDATE graph_nodes SET community = NULL");
+            for (const [nodeId, communityId] of assignment) {
+                updateCommunity.run(communityId, nodeId);
+            }
+        })();
+        return rootToMin.size;
+    }
+    /**
+     * Return the top-N most-connected graph nodes (god nodes).
+     */
+    getGodNodes(topN = 10) {
+        this.ensureOpen();
+        const limit = Math.min(Math.max(1, topN), 50);
+        const rows = this.db.prepare(`
+      SELECT * FROM (
+        SELECT gn.*, (
+          SELECT COUNT(*) FROM graph_edges e
+          WHERE e.source_node_id = gn.id OR e.target_node_id = gn.id
+        ) AS degree
+        FROM graph_nodes gn
+      )
+      WHERE degree > 0
+      ORDER BY degree DESC
+      LIMIT ?
+    `).all(limit);
+        return rows.map(r => ({
+            id: Number(r.id),
+            symbolId: r.symbol_id ? Number(r.symbol_id) : undefined,
+            file: String(r.file ?? ""),
+            name: String(r.name ?? ""),
+            kind: String(r.kind ?? ""),
+            signature: String(r.signature ?? ""),
+            line: r.line ? Number(r.line) : undefined,
+            column: r.column ? Number(r.column) : undefined,
+            community: r.community ? Number(r.community) : undefined,
+        }));
+    }
+    /**
+     * Return summary graph statistics.
+     */
+    getGraphStats() {
+        this.ensureOpen();
+        const nodeCount = this.db.prepare("SELECT COUNT(*) AS c FROM graph_nodes").get().c;
+        const edgeCount = this.db.prepare("SELECT COUNT(*) AS c FROM graph_edges").get().c;
+        const communityCount = this.db.prepare("SELECT COUNT(DISTINCT community) AS c FROM graph_nodes WHERE community IS NOT NULL").get().c;
+        const unreferencedNodeCount = this.db.prepare(`
+      SELECT COUNT(*) AS c FROM graph_nodes gn
+      WHERE NOT EXISTS (SELECT 1 FROM graph_edges e WHERE e.source_node_id = gn.id OR e.target_node_id = gn.id)
+    `).get().c;
+        const nodeKinds = this.db.prepare("SELECT kind, COUNT(*) AS c FROM graph_nodes GROUP BY kind ORDER BY c DESC").all();
+        const edgeKinds = this.db.prepare("SELECT kind, COUNT(*) AS c FROM graph_edges GROUP BY kind ORDER BY c DESC").all();
+        const confidenceBreakdown = this.db.prepare("SELECT confidence, COUNT(*) AS c FROM graph_edges GROUP BY confidence ORDER BY c DESC").all();
+        const maxDegree = edgeCount > 0
+            ? this.db.prepare(`
+        SELECT MAX(d) AS c FROM (
+          SELECT COUNT(*) AS d, source_node_id FROM graph_edges GROUP BY source_node_id
+        )
+      `).get().c
+            : 0;
+        const avgDegree = edgeCount > 0 && nodeCount > 0
+            ? Math.round((edgeCount * 2) / nodeCount * 10) / 10
+            : 0;
+        const communityCountVal = communityCount > 0 ? communityCount : 0;
+        return {
+            nodeCount: Number(nodeCount),
+            edgeCount: Number(edgeCount),
+            communityCount: Number(communityCountVal),
+            unreferencedNodeCount: Number(unreferencedNodeCount),
+            maxDegree: Number(maxDegree ?? 0),
+            avgDegree: Number(avgDegree),
+            nodeKinds: Object.fromEntries(nodeKinds.map(r => [r.kind, r.c])),
+            edgeKinds: Object.fromEntries(edgeKinds.map(r => [r.kind, r.c])),
+            confidenceBreakdown: Object.fromEntries(confidenceBreakdown.map(r => [r.confidence, r.c])),
+        };
+    }
+    // ── Cycle detection ──────────────────────────────────
+    detectCycles() {
+        this.ensureOpen();
+        // Use recursive CTE to find cycles: walk edges and detect when we revisit a node
+        const rows = this.db.prepare(`
+      WITH RECURSIVE walk(path, last_node, kind, depth, has_cycle) AS (
+        SELECT
+          ',' || CAST(e.source_node_id AS TEXT) || ',' || CAST(e.target_node_id AS TEXT) || ',',
+          e.target_node_id,
+          e.kind,
+          1,
+          0
+        FROM graph_edges e
+        UNION ALL
+        SELECT
+          w.path || CAST(e.target_node_id AS TEXT) || ',',
+          e.target_node_id,
+          e.kind,
+          w.depth + 1,
+          CASE WHEN w.path LIKE '%,' || CAST(e.target_node_id AS TEXT) || ',%' THEN 1 ELSE 0 END
+        FROM walk w
+        JOIN graph_edges e ON e.source_node_id = w.last_node
+        WHERE w.depth < 20 AND w.has_cycle = 0
+      )
+      SELECT DISTINCT w.path, w.kind, w.depth
+      FROM walk w
+      WHERE w.has_cycle = 1
+      LIMIT 50
+    `).all();
+        // Batch-resolve node IDs → names with ONE query instead of N
+        const cycles = rows.map(r => {
+            const ids = r.path.split(',').filter(Boolean).map(Number);
+            return { ids, kind: r.kind, length: new Set(ids).size };
+        });
+        const nameMap = this.resolveNodeNames(cycles);
+        return cycles.map(c => ({
+            cycle: c.ids.slice(0, 10).map(id => nameMap.get(id) ?? `?${id}`),
+            kind: c.kind,
+            length: c.length,
+        }));
+    }
+    /** Batch-resolve node IDs to names — one query instead of N. */
+    resolveNodeNames(cycles) {
+        const allIds = new Set();
+        for (const c of cycles)
+            for (const id of c.ids)
+                allIds.add(id);
+        const samples = [...allIds].slice(0, 100);
+        if (samples.length === 0)
+            return new Map();
+        const placeholders = samples.map(() => '?').join(',');
+        const rows = this.db.prepare(`SELECT id, name FROM graph_nodes WHERE id IN (${placeholders})`).all(...samples);
+        return new Map(rows.map(n => [n.id, n.name]));
+    }
+    // ── Trigram FTS search (CJK support) ─────────────────
+    searchGraphNodesTrigram(query, limit = 20) {
+        this.ensureOpen();
+        const safeLimit = Math.min(Math.max(1, limit), 50);
+        // Escape FTS5 special characters
+        const escaped = String(query).replace(/['"]/g, '').trim();
+        if (!escaped)
+            return [];
+        try {
+            const rows = this.db.prepare(`
+        SELECT gn.* FROM nodes_trigram_fts f
+        JOIN graph_nodes gn ON gn.id = f.rowid
+        WHERE nodes_trigram_fts MATCH ?
+        LIMIT ?
+      `).all(escaped, safeLimit);
+            return rows.map(r => ({
+                id: Number(r.id),
+                name: String(r.name ?? ''),
+                kind: String(r.kind ?? ''),
+                file: String(r.file ?? ''),
+                line: r.line != null ? Number(r.line) : undefined,
+                column: r.column != null ? Number(r.column) : undefined,
+                signature: String(r.signature ?? ''),
+                community: r.community != null ? Number(r.community) : undefined,
+                symbolId: r.symbol_id != null ? Number(r.symbol_id) : undefined,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    // ── Name segment vocab search (fast partial match) ───
+    searchGraphNodesBySegment(segment, limit = 20) {
+        this.ensureOpen();
+        const safeLimit = Math.min(Math.max(1, limit), 50);
+        const seg = String(segment).toLowerCase().trim();
+        if (!seg)
+            return [];
+        const rows = this.db.prepare(`
+      SELECT DISTINCT gn.* FROM name_segment_vocab nsv
+      JOIN graph_nodes gn ON gn.id = nsv.node_id
+      WHERE nsv.segment LIKE ? ESCAPE '\\'
+      ORDER BY gn.name
+      LIMIT ?
+    `).all(`${seg}%`, safeLimit);
+        return rows.map(r => ({
+            id: Number(r.id),
+            name: String(r.name ?? ''),
+            kind: String(r.kind ?? ''),
+            file: String(r.file ?? ''),
+            line: r.line != null ? Number(r.line) : undefined,
+            column: r.column != null ? Number(r.column) : undefined,
+            signature: String(r.signature ?? ''),
+            community: r.community != null ? Number(r.community) : undefined,
+            symbolId: r.symbol_id != null ? Number(r.symbol_id) : undefined,
+        }));
+    }
+    // ── Session reflections (work memory) ────────────────
+    recordReflection(sessionId, goal, task, symbols, files) {
+        this.ensureOpen();
+        this.db.prepare(`
+      INSERT INTO session_reflections (session_id, goal, task, symbols, files)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(String(sessionId), String(goal), String(task), JSON.stringify(symbols ?? []), JSON.stringify(files ?? []));
+    }
+    getSessionReflections(sessionId, limit = 20) {
+        this.ensureOpen();
+        const safeLimit = Math.min(Math.max(1, limit), 100);
+        let rows;
+        if (sessionId) {
+            rows = this.db.prepare(`
+        SELECT * FROM session_reflections WHERE session_id = ? ORDER BY timestamp DESC LIMIT ?
+      `).all(sessionId, safeLimit);
+        }
+        else {
+            rows = this.db.prepare(`
+        SELECT * FROM session_reflections ORDER BY timestamp DESC LIMIT ?
+      `).all(safeLimit);
+        }
+        return rows.map(r => ({
+            id: Number(r.id),
+            sessionId: String(r.session_id ?? ''),
+            goal: String(r.goal ?? ''),
+            task: String(r.task ?? ''),
+            symbols: String(r.symbols ?? '[]'),
+            files: String(r.files ?? '[]'),
+            timestamp: String(r.timestamp ?? ''),
+        }));
+    }
 }
 // ─── Factory ───────────────────────────────────────────────
 let globalStore = null;