homegraph 1.5.1 → 1.5.3

package/dist/db/queries.js

@@ -133,6 +133,7 @@ function rowToFileRecord(row) {
         indexedAt: row.indexed_at,
         nodeCount: row.node_count,
         errors: row.errors ? (0, utils_1.safeJsonParse)(row.errors, undefined) : undefined,
+        generated: row.generated === 1,
     };
 }
 /**
@@ -152,6 +153,11 @@ class QueryBuilder {
     maxCacheSize = 1000;
     /** Attached prebuilt OHOS API db (see arkts.ts). */
     ohosApiDbPath = null;
+    /**
+     * When false, name/search lookups skip the project `nodes` table and only
+     * return attached `ohos_api` rows (`HOMEGRAPH_SOURCES=sdk`). Default true.
+     */
+    includeProjectNodes = true;
     // Prepared statements (lazily initialized)
     stmts = {};
     // Multi-row INSERT statements, cached per (statement kind × row count).
@@ -202,6 +208,16 @@ class QueryBuilder {
         this.stmts = {};
         this.batchStmts.clear();
     }
+    /**
+     * Toggle whether project-index nodes participate in lookups.
+     * SDK-only sessions set this false after opening the project db for ATTACH.
+     */
+    setIncludeProjectNodes(include) {
+        this.includeProjectNodes = include;
+    }
+    getIncludeProjectNodes() {
+        return this.includeProjectNodes;
+    }
     /** Attach a versioned OHOS API db for federated symbol lookup. */
     attachOhosApiDb(dbPath) {
         if (dbPath === this.ohosApiDbPath)
@@ -255,20 +271,20 @@ class QueryBuilder {
      */
     insertNode(node) {
         if (!this.stmts.insertNode) {
-            this.stmts.insertNode = this.db.prepare(`
-        INSERT OR REPLACE INTO nodes (
-          id, kind, name, qualified_name, file_path, language,
-          start_line, end_line, start_column, end_column,
-          docstring, signature, visibility,
-          is_exported, is_async, is_static, is_abstract,
-          decorators, type_parameters, return_type, updated_at
-        ) VALUES (
-          @id, @kind, @name, @qualifiedName, @filePath, @language,
-          @startLine, @endLine, @startColumn, @endColumn,
-          @docstring, @signature, @visibility,
-          @isExported, @isAsync, @isStatic, @isAbstract,
-          @decorators, @typeParameters, @returnType, @updatedAt
-        )
+            this.stmts.insertNode = this.db.prepare(`
+        INSERT OR REPLACE INTO nodes (
+          id, kind, name, qualified_name, file_path, language,
+          start_line, end_line, start_column, end_column,
+          docstring, signature, visibility,
+          is_exported, is_async, is_static, is_abstract,
+          decorators, type_parameters, return_type, updated_at
+        ) VALUES (
+          @id, @kind, @name, @qualifiedName, @filePath, @language,
+          @startLine, @endLine, @startColumn, @endColumn,
+          @docstring, @signature, @visibility,
+          @isExported, @isAsync, @isStatic, @isAbstract,
+          @decorators, @typeParameters, @returnType, @updatedAt
+        )
       `);
         }
         // Validate required fields to prevent SQLite bind errors
@@ -364,29 +380,29 @@ class QueryBuilder {
      */
     updateNode(node) {
         if (!this.stmts.updateNode) {
-            this.stmts.updateNode = this.db.prepare(`
-        UPDATE nodes SET
-          kind = @kind,
-          name = @name,
-          qualified_name = @qualifiedName,
-          file_path = @filePath,
-          language = @language,
-          start_line = @startLine,
-          end_line = @endLine,
-          start_column = @startColumn,
-          end_column = @endColumn,
-          docstring = @docstring,
-          signature = @signature,
-          visibility = @visibility,
-          is_exported = @isExported,
-          is_async = @isAsync,
-          is_static = @isStatic,
-          is_abstract = @isAbstract,
-          decorators = @decorators,
-          type_parameters = @typeParameters,
-          return_type = @returnType,
-          updated_at = @updatedAt
-        WHERE id = @id
+            this.stmts.updateNode = this.db.prepare(`
+        UPDATE nodes SET
+          kind = @kind,
+          name = @name,
+          qualified_name = @qualifiedName,
+          file_path = @filePath,
+          language = @language,
+          start_line = @startLine,
+          end_line = @endLine,
+          start_column = @startColumn,
+          end_column = @endColumn,
+          docstring = @docstring,
+          signature = @signature,
+          visibility = @visibility,
+          is_exported = @isExported,
+          is_async = @isAsync,
+          is_static = @isStatic,
+          is_abstract = @isAbstract,
+          decorators = @decorators,
+          type_parameters = @typeParameters,
+          return_type = @returnType,
+          updated_at = @updatedAt
+        WHERE id = @id
       `);
         }
         // Invalidate cache before update
@@ -518,12 +534,12 @@ class QueryBuilder {
         const placeholders = variants.map(() => '?').join(', ');
         const whens = variants.map(() => 'WHEN ? THEN ?').join(' ');
         const rows = this.db
-            .prepare(`SELECT name, COUNT(DISTINCT CASE segment ${whens} END) AS matches
-         FROM name_segment_vocab
-         WHERE segment IN (${placeholders})
-         GROUP BY name
-         HAVING matches >= ?
-         ORDER BY matches DESC, length(name) ASC
+            .prepare(`SELECT name, COUNT(DISTINCT CASE segment ${whens} END) AS matches
+         FROM name_segment_vocab
+         WHERE segment IN (${placeholders})
+         GROUP BY name
+         HAVING matches >= ?
+         ORDER BY matches DESC, length(name) ASC
          LIMIT ?`)
             .all(...variants.flatMap((v) => [v.segment, v.word]), ...variants.map((v) => v.segment), minWords, limit);
         return rows;
@@ -535,7 +551,7 @@ class QueryBuilder {
             return new Map();
         const placeholders = segments.map(() => '?').join(', ');
         const rows = this.db
-            .prepare(`SELECT segment, COUNT(*) AS n FROM name_segment_vocab
+            .prepare(`SELECT segment, COUNT(*) AS n FROM name_segment_vocab
          WHERE segment IN (${placeholders}) GROUP BY segment`)
             .all(...segments);
         return new Map(rows.map((r) => [r.segment, r.n]));
@@ -695,15 +711,15 @@ class QueryBuilder {
             // protobuf stub) outranks the real `server/etcdserver/server.go`
             // (470 edges) by 4×, and the boost would push the agent toward
             // generated code.
-            this.stmts.getDominantFile = this.db.prepare(`
-        SELECT n.file_path AS file_path, COUNT(*) AS edge_count
-        FROM edges e
-        JOIN nodes n ON e.source = n.id
-        JOIN nodes m ON e.target = m.id
-        WHERE n.file_path = m.file_path
-        GROUP BY n.file_path
-        ORDER BY edge_count DESC
-        LIMIT 20
+            this.stmts.getDominantFile = this.db.prepare(`
+        SELECT n.file_path AS file_path, COUNT(*) AS edge_count
+        FROM edges e
+        JOIN nodes n ON e.source = n.id
+        JOIN nodes m ON e.target = m.id
+        WHERE n.file_path = m.file_path
+        GROUP BY n.file_path
+        ORDER BY edge_count DESC
+        LIMIT 20
       `);
         }
         const rows = this.stmts.getDominantFile.all();
@@ -730,13 +746,13 @@ class QueryBuilder {
      */
     getTopRouteFile() {
         if (!this.stmts.getTopRouteFile) {
-            this.stmts.getTopRouteFile = this.db.prepare(`
-        SELECT file_path, COUNT(*) AS cnt
-        FROM nodes
-        WHERE kind = 'route'
-        GROUP BY file_path
-        ORDER BY cnt DESC
-        LIMIT 20
+            this.stmts.getTopRouteFile = this.db.prepare(`
+        SELECT file_path, COUNT(*) AS cnt
+        FROM nodes
+        WHERE kind = 'route'
+        GROUP BY file_path
+        ORDER BY cnt DESC
+        LIMIT 20
       `);
         }
         const rows = this.stmts.getTopRouteFile.all();
@@ -767,21 +783,21 @@ class QueryBuilder {
             // Edge kind varies across framework resolvers: Spring/Rails/
             // Laravel/Drupal emit `references`, Express emits `calls`. Accept
             // both — the semantic is the same (route → its handler).
-            this.stmts.getRoutingManifest = this.db.prepare(`
-        SELECT
-          r.name AS url,
-          h.name AS handler,
-          h.file_path AS handler_file,
-          h.start_line AS handler_line,
-          h.kind AS handler_kind
-        FROM nodes r
-        JOIN edges e ON e.source = r.id
-        JOIN nodes h ON e.target = h.id
-        WHERE r.kind = 'route'
-          AND e.kind IN ('references', 'calls')
-          AND h.kind IN ('function', 'method', 'class')
-        ORDER BY r.file_path, r.start_line
-        LIMIT ?
+            this.stmts.getRoutingManifest = this.db.prepare(`
+        SELECT
+          r.name AS url,
+          h.name AS handler,
+          h.file_path AS handler_file,
+          h.start_line AS handler_line,
+          h.kind AS handler_kind
+        FROM nodes r
+        JOIN edges e ON e.source = r.id
+        JOIN nodes h ON e.target = h.id
+        WHERE r.kind = 'route'
+          AND e.kind IN ('references', 'calls')
+          AND h.kind IN ('function', 'method', 'class')
+        ORDER BY r.file_path, r.start_line
+        LIMIT ?
       `);
         }
         const rows = this.stmts.getRoutingManifest.all(limit);
@@ -878,15 +894,21 @@ class QueryBuilder {
      * Get nodes by exact name match (uses idx_nodes_name index)
      */
     getNodesByName(name) {
-        if (!this.stmts.getNodesByName) {
-            this.stmts.getNodesByName = this.db.prepare('SELECT * FROM nodes WHERE name = ?');
+        const main = [];
+        if (this.includeProjectNodes) {
+            if (!this.stmts.getNodesByName) {
+                // Content-derived order (not insertion/rowid order): sync appends nodes
+                // as files change, so without ORDER BY the same tree can resolve
+                // differently than a full rebuild that writes in scan order.
+                this.stmts.getNodesByName = this.db.prepare('SELECT * FROM nodes WHERE name = ? ORDER BY file_path, start_line');
+            }
+            const rows = this.stmts.getNodesByName.all(name);
+            main.push(...rows.map(rowToNode));
         }
-        const rows = this.stmts.getNodesByName.all(name);
-        const main = rows.map(rowToNode);
         if (!this.hasOhosApiAttached())
             return main;
         const apiRows = this.db
-            .prepare('SELECT * FROM ohos_api.nodes WHERE name = ?')
+            .prepare('SELECT * FROM ohos_api.nodes WHERE name = ? ORDER BY file_path, start_line')
             .all(name);
         const seen = new Set(main.map((n) => n.id));
         const api = apiRows.map((r) => this.mapOhosApiNodeRow(r)).filter((n) => !seen.has(n.id));
@@ -942,12 +964,17 @@ class QueryBuilder {
         const text = parsed.text;
         const kinds = mergedKinds;
         const languages = mergedLanguages;
+        // SDK-only: skip project FTS entirely; federate OHOS API hits only.
+        if (!this.includeProjectNodes) {
+            if (!this.hasOhosApiAttached() || text.length < 2)
+                return [];
+            return this.mergeOhosApiTextSearch(text, { kinds, languages, limit }, []);
+        }
         // First try FTS5 with prefix matching
         let results = text
             ? this.searchNodesFTS(text, { kinds, languages, limit, offset })
             // Over-fetch by 5× when running filter-only (no text). The
-            // post-scoring path: + name: filters can be very selective, so
-            // a smaller multiplier risks returning fewer than `limit`
+            // post-scoring path: + name: filters can be very selective, so      // a smaller multiplier risks returning fewer than `limit`
             // results despite the DB having plenty of matches.
             : this.searchAllByFilters({ kinds, languages, limit: limit * 5 });
         // If no FTS results, try LIKE-based substring search
@@ -1036,10 +1063,10 @@ class QueryBuilder {
         const seen = new Set(existing.map((r) => r.node.id));
         const merged = [...existing];
         const apiLimit = Math.min(20, Math.max(5, Math.floor(limit / 4)));
-        let sql = `
-      SELECT nodes.*, 0.9 as score
-      FROM ohos_api.nodes
-      WHERE (name LIKE ? OR qualified_name LIKE ?)
+        let sql = `
+      SELECT nodes.*, 0.9 as score
+      FROM ohos_api.nodes
+      WHERE (name LIKE ? OR qualified_name LIKE ?)
     `;
         const pattern = `%${text}%`;
         const params = [pattern, pattern];
@@ -1178,11 +1205,11 @@ class QueryBuilder {
         // Fetch 5x requested limit so post-hoc rescoring (kindBonus, pathRelevance,
         // nameMatchBonus) can promote results that BM25 alone undervalues.
         const ftsLimit = Math.max(limit * 5, 100);
-        let sql = `
-      SELECT nodes.*, bm25(nodes_fts, 0, 20, 5, 1, 2) as score
-      FROM nodes_fts
-      JOIN nodes ON nodes_fts.id = nodes.id
-      WHERE nodes_fts MATCH ?
+        let sql = `
+      SELECT nodes.*, bm25(nodes_fts, 0, 20, 5, 1, 2) as score
+      FROM nodes_fts
+      JOIN nodes ON nodes_fts.id = nodes.id
+      WHERE nodes_fts MATCH ?
     `;
         const params = [ftsQuery];
         if (kinds && kinds.length > 0) {
@@ -1213,21 +1240,21 @@ class QueryBuilder {
      */
     searchNodesLike(query, options) {
         const { kinds, languages, limit = 100, offset = 0 } = options;
-        let sql = `
-      SELECT nodes.*,
-        CASE
-          WHEN name = ? THEN 1.0
-          WHEN name LIKE ? THEN 0.9
-          WHEN name LIKE ? THEN 0.8
-          WHEN qualified_name LIKE ? THEN 0.7
-          ELSE 0.5
-        END as score
-      FROM nodes
-      WHERE (
-        name LIKE ? OR
-        qualified_name LIKE ? OR
-        name LIKE ?
-      )
+        let sql = `
+      SELECT nodes.*,
+        CASE
+          WHEN name = ? THEN 1.0
+          WHEN name LIKE ? THEN 0.9
+          WHEN name LIKE ? THEN 0.8
+          WHEN qualified_name LIKE ? THEN 0.7
+          ELSE 0.5
+        END as score
+      FROM nodes
+      WHERE (
+        name LIKE ? OR
+        qualified_name LIKE ? OR
+        name LIKE ?
+      )
     `;
         // Pattern variants for better matching
         const exactMatch = query;
@@ -1272,6 +1299,42 @@ class QueryBuilder {
         if (names.length === 0)
             return [];
         const { kinds, languages, limit = 50 } = options;
+        // SDK-only: skip project co-location passes; exact-name against ohos_api only.
+        if (!this.includeProjectNodes) {
+            if (!this.hasOhosApiAttached())
+                return [];
+            const perNameLimit = Math.max(8, Math.ceil(limit / names.length));
+            const allResults = [];
+            const seenIds = new Set();
+            for (const name of names) {
+                let apiSql = `
+          SELECT nodes.*, 0.95 as score
+          FROM ohos_api.nodes
+          WHERE name COLLATE NOCASE = ?
+        `;
+                const apiParams = [name];
+                if (kinds && kinds.length > 0) {
+                    apiSql += ` AND kind IN (${kinds.map(() => '?').join(',')})`;
+                    apiParams.push(...kinds);
+                }
+                if (languages && languages.length > 0) {
+                    apiSql += ` AND language IN (${languages.map(() => '?').join(',')})`;
+                    apiParams.push(...languages);
+                }
+                apiSql += ' LIMIT ?';
+                apiParams.push(perNameLimit);
+                const apiRows = this.db.prepare(apiSql).all(...apiParams);
+                for (const row of apiRows) {
+                    const node = this.mapOhosApiNodeRow(row);
+                    if (seenIds.has(node.id))
+                        continue;
+                    seenIds.add(node.id);
+                    allResults.push({ node, score: row.score });
+                }
+            }
+            allResults.sort((a, b) => b.score - a.score);
+            return allResults.slice(0, limit);
+        }
         // Two-pass approach to handle common names (e.g., "run" has 40+ matches):
         // Pass 1: Find which files contain distinctive (rare) symbols from the query.
         // Pass 2: Query each name, boosting results that co-locate with distinctive symbols.
@@ -1301,10 +1364,10 @@ class QueryBuilder {
         const allResults = [];
         const seenIds = new Set();
         for (const name of names) {
-            let sql = `
-        SELECT nodes.*, 1.0 as score
-        FROM nodes
-        WHERE name COLLATE NOCASE = ?
+            let sql = `
+        SELECT nodes.*, 1.0 as score
+        FROM nodes
+        WHERE name COLLATE NOCASE = ?
       `;
             const params = [name];
             if (kinds && kinds.length > 0) {
@@ -1335,10 +1398,10 @@ class QueryBuilder {
                 allResults.push(r);
             }
             if (this.hasOhosApiAttached()) {
-                let apiSql = `
-          SELECT nodes.*, 0.95 as score
-          FROM ohos_api.nodes
-          WHERE name COLLATE NOCASE = ?
+                let apiSql = `
+          SELECT nodes.*, 0.95 as score
+          FROM ohos_api.nodes
+          WHERE name COLLATE NOCASE = ?
         `;
                 const apiParams = [name];
                 if (kinds && kinds.length > 0) {
@@ -1374,10 +1437,10 @@ class QueryBuilder {
      */
     findNodesByNameSubstring(substring, options = {}) {
         const { kinds, languages, limit = 30, excludePrefix } = options;
-        let sql = `
-      SELECT nodes.*, 1.0 as score
-      FROM nodes
-      WHERE name LIKE ?
+        let sql = `
+      SELECT nodes.*, 1.0 as score
+      FROM nodes
+      WHERE name LIKE ?
     `;
         const params = [`%${substring}%`];
         // Exclude prefix matches (handled by FTS-based prefix search in Step 2b)
@@ -1409,9 +1472,9 @@ class QueryBuilder {
      */
     insertEdge(edge) {
         if (!this.stmts.insertEdge) {
-            this.stmts.insertEdge = this.db.prepare(`
-        INSERT OR IGNORE INTO edges (source, target, kind, metadata, line, col, provenance)
-        VALUES (@source, @target, @kind, @metadata, @line, @col, @provenance)
+            this.stmts.insertEdge = this.db.prepare(`
+        INSERT OR IGNORE INTO edges (source, target, kind, metadata, line, col, provenance)
+        VALUES (@source, @target, @kind, @metadata, @line, @col, @provenance)
       `);
         }
         this.stmts.insertEdge.run({
@@ -1538,12 +1601,12 @@ class QueryBuilder {
      * it. One indexed query (idx_nodes_file_path + idx_edges_target_kind).
      */
     getDependentFilePaths(filePath) {
-        const sql = `SELECT DISTINCT src.file_path AS fp
-      FROM edges e
-      JOIN nodes tgt ON tgt.id = e.target
-      JOIN nodes src ON src.id = e.source
-      WHERE tgt.file_path = ?
-        AND e.kind != 'contains'
+        const sql = `SELECT DISTINCT src.file_path AS fp
+      FROM edges e
+      JOIN nodes tgt ON tgt.id = e.target
+      JOIN nodes src ON src.id = e.source
+      WHERE tgt.file_path = ?
+        AND e.kind != 'contains'
         AND src.file_path != ?`;
         const rows = this.db.prepare(sql).all(filePath, filePath);
         return rows.map((r) => r.fp);
@@ -1555,12 +1618,12 @@ class QueryBuilder {
      * (all kinds except `contains`); same reason imports-only is insufficient.
      */
     getDependencyFilePaths(filePath) {
-        const sql = `SELECT DISTINCT tgt.file_path AS fp
-      FROM edges e
-      JOIN nodes src ON src.id = e.source
-      JOIN nodes tgt ON tgt.id = e.target
-      WHERE src.file_path = ?
-        AND e.kind != 'contains'
+        const sql = `SELECT DISTINCT tgt.file_path AS fp
+      FROM edges e
+      JOIN nodes src ON src.id = e.source
+      JOIN nodes tgt ON tgt.id = e.target
+      WHERE src.file_path = ?
+        AND e.kind != 'contains'
         AND tgt.file_path != ?`;
         const rows = this.db.prepare(sql).all(filePath, filePath);
         return rows.map((r) => r.fp);
@@ -1576,13 +1639,13 @@ class QueryBuilder {
      * {@link getDependentFilePaths}: all kinds except `contains`.
      */
     getCrossFileIncomingEdgesWithTarget(filePath) {
-        const sql = `SELECT e.*, tgt.name AS target_name, tgt.kind AS target_kind,
-        src.file_path AS source_file_path, src.language AS source_language
-      FROM edges e
-      JOIN nodes tgt ON tgt.id = e.target
-      JOIN nodes src ON src.id = e.source
-      WHERE tgt.file_path = ?
-        AND e.kind != 'contains'
+        const sql = `SELECT e.*, tgt.name AS target_name, tgt.kind AS target_kind,
+        src.file_path AS source_file_path, src.language AS source_language
+      FROM edges e
+      JOIN nodes tgt ON tgt.id = e.target
+      JOIN nodes src ON src.id = e.source
+      WHERE tgt.file_path = ?
+        AND e.kind != 'contains'
         AND src.file_path != ?`;
         const rows = this.db.prepare(sql).all(filePath, filePath);
         return rows.map(row => ({
@@ -1599,10 +1662,10 @@ class QueryBuilder {
      */
     deleteArkTSCrossFileCallEdges() {
         const result = this.db
-            .prepare(`DELETE FROM edges
-         WHERE kind = 'calls'
-           AND provenance = 'heuristic'
-           AND metadata LIKE '%"synthesizedBy":"arkanalyzer"%'
+            .prepare(`DELETE FROM edges
+         WHERE kind = 'calls'
+           AND provenance = 'heuristic'
+           AND metadata LIKE '%"synthesizedBy":"arkanalyzer"%'
            AND metadata LIKE '%"sourceFile"%'`)
             .run();
         return result.changes;
@@ -1615,17 +1678,18 @@ class QueryBuilder {
      */
     upsertFile(file) {
         if (!this.stmts.upsertFile) {
-            this.stmts.upsertFile = this.db.prepare(`
-        INSERT INTO files (path, content_hash, language, size, modified_at, indexed_at, node_count, errors)
-        VALUES (@path, @contentHash, @language, @size, @modifiedAt, @indexedAt, @nodeCount, @errors)
-        ON CONFLICT(path) DO UPDATE SET
-          content_hash = @contentHash,
-          language = @language,
-          size = @size,
-          modified_at = @modifiedAt,
-          indexed_at = @indexedAt,
-          node_count = @nodeCount,
-          errors = @errors
+            this.stmts.upsertFile = this.db.prepare(`
+        INSERT INTO files (path, content_hash, language, size, modified_at, indexed_at, node_count, errors, generated)
+        VALUES (@path, @contentHash, @language, @size, @modifiedAt, @indexedAt, @nodeCount, @errors, @generated)
+        ON CONFLICT(path) DO UPDATE SET
+          content_hash = @contentHash,
+          language = @language,
+          size = @size,
+          modified_at = @modifiedAt,
+          indexed_at = @indexedAt,
+          node_count = @nodeCount,
+          errors = @errors,
+          generated = @generated
       `);
         }
         this.stmts.upsertFile.run({
@@ -1637,6 +1701,7 @@ class QueryBuilder {
             indexedAt: file.indexedAt,
             nodeCount: file.nodeCount,
             errors: file.errors ? JSON.stringify(file.errors) : null,
+            generated: file.generated ? 1 : 0,
         });
     }
     /**
@@ -1699,9 +1764,9 @@ class QueryBuilder {
      */
     insertUnresolvedRef(ref) {
         if (!this.stmts.insertUnresolved) {
-            this.stmts.insertUnresolved = this.db.prepare(`
-        INSERT INTO unresolved_refs (from_node_id, reference_name, reference_kind, line, col, candidates, file_path, language)
-        VALUES (@fromNodeId, @referenceName, @referenceKind, @line, @col, @candidates, @filePath, @language)
+            this.stmts.insertUnresolved = this.db.prepare(`
+        INSERT INTO unresolved_refs (from_node_id, reference_name, reference_kind, line, col, candidates, file_path, language)
+        VALUES (@fromNodeId, @referenceName, @referenceKind, @line, @col, @candidates, @filePath, @language)
       `);
         }
         this.stmts.insertUnresolved.run({
@@ -1994,6 +2059,107 @@ class QueryBuilder {
         }
         return [...names];
     }
+    /**
+     * Resolution edges targeting any of the given node names — candidates for the
+     * sync rebind pass when a definition set changes. Includes source file/language
+     * so a dropped edge can be resurrected as its original unresolved ref.
+     *
+     * Names matching more than `perNameCeiling` edges are skipped entirely, same
+     * rationale and same default as {@link getRetryableFailedReferences}: at that
+     * population the name is generic (`get`, `clear`, …); one definition changing
+     * won't flip most of them, and rebinding an arbitrary subset is both wasted
+     * work and incoherent coverage.
+     */
+    getResolutionEdgesByTargetName(names, perNameCeiling = 500) {
+        if (names.length === 0)
+            return [];
+        // Pass 1: per-name edge counts, chunked under the SQLite parameter limit.
+        const keep = [];
+        for (let i = 0; i < names.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = names.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const counts = this.db
+                .prepare(`SELECT tgt.name AS name, COUNT(*) AS count
+             FROM edges e
+             JOIN nodes tgt ON tgt.id = e.target
+            WHERE tgt.name IN (${placeholders})
+              AND (e.provenance IS NULL OR e.provenance != 'heuristic')
+            GROUP BY tgt.name`)
+                .all(...chunk);
+            for (const row of counts) {
+                if (row.count <= perNameCeiling)
+                    keep.push(row.name);
+            }
+        }
+        if (keep.length === 0)
+            return [];
+        // Pass 2: load the surviving edges with the source file context a
+        // resurrection needs.
+        const out = [];
+        for (let i = 0; i < keep.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = keep.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT e.*, src.file_path AS source_file_path, src.language AS source_language
+             FROM edges e
+             JOIN nodes tgt ON tgt.id = e.target
+             JOIN nodes src ON src.id = e.source
+            WHERE tgt.name IN (${placeholders})
+              AND (e.provenance IS NULL OR e.provenance != 'heuristic')`)
+                .all(...chunk);
+            for (const row of rows) {
+                out.push({
+                    ...rowToEdge(row),
+                    edgeId: row.id,
+                    sourceFilePath: row.source_file_path,
+                    sourceLanguage: row.source_language,
+                });
+            }
+        }
+        return out;
+    }
+    /** Delete edges by primary key — the rebind pass's half of a re-resolution. */
+    deleteEdgesByIds(edgeIds) {
+        if (edgeIds.length === 0)
+            return 0;
+        let changed = 0;
+        this.db.transaction(() => {
+            for (let i = 0; i < edgeIds.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+                const chunk = edgeIds.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+                const placeholders = chunk.map(() => '?').join(',');
+                changed += this.db.prepare(`DELETE FROM edges WHERE id IN (${placeholders})`).run(...chunk).changes;
+            }
+        })();
+        return changed;
+    }
+    /**
+     * Distinct `file\0name` pairs defined by the given files — the shape sync's
+     * definition delta needs.
+     *
+     * Deliberately NOT `getNodeNamesByFiles`: a bare name set is taken over the
+     * WHOLE changed batch, so a name that moves between two files in one commit
+     * (or exists in one changed file and is newly added to another) appears on
+     * both sides and cancels out of the symmetric difference — even though a
+     * definition genuinely appeared or vanished and every reference to that name
+     * repo-wide may now bind elsewhere. Keying by file makes each definition its
+     * own fact, so the move is seen as one removal plus one addition.
+     */
+    getNodeNamePairsByFiles(filePaths) {
+        const pairs = new Set();
+        if (filePaths.length === 0)
+            return pairs;
+        for (let i = 0; i < filePaths.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = filePaths.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT DISTINCT file_path, name FROM nodes WHERE file_path IN (${placeholders})`)
+                .all(...chunk);
+            // NUL-joined: a path or a symbol name can contain a space, never a NUL.
+            for (const row of rows)
+                pairs.add(`${row.file_path}\0${row.name}`);
+        }
+        return pairs;
+    }
     /**
      * Get unresolved references scoped to specific file paths.
      * Uses the idx_unresolved_file_path index for efficient lookup.
@@ -2085,11 +2251,11 @@ class QueryBuilder {
      */
     getStats() {
         // Single query for all three aggregate counts
-        const counts = this.db.prepare(`
-      SELECT
-        (SELECT COUNT(*) FROM nodes) AS node_count,
-        (SELECT COUNT(*) FROM edges) AS edge_count,
-        (SELECT COUNT(*) FROM files) AS file_count
+        const counts = this.db.prepare(`
+      SELECT
+        (SELECT COUNT(*) FROM nodes) AS node_count,
+        (SELECT COUNT(*) FROM edges) AS edge_count,
+        (SELECT COUNT(*) FROM files) AS file_count
     `).get();
         const nodesByKind = {};
         const nodeKindRows = this.db
@@ -2120,6 +2286,7 @@ class QueryBuilder {
             edgesByKind,
             filesByLanguage,
             dbSizeBytes: 0, // Set by caller using DatabaseConnection.getSize()
+            walSizeBytes: 0, // Set by caller using DatabaseConnection.getWalSizeBytes()
             lastUpdated: Date.now(),
         };
     }