homegraph 1.4.1 → 1.5.1

package/dist/db/queries.js

@@ -154,9 +154,54 @@ class QueryBuilder {
     ohosApiDbPath = null;
     // Prepared statements (lazily initialized)
     stmts = {};
+    // Multi-row INSERT statements, cached per (statement kind × row count).
+    batchStmts = new Map();
+    static BATCH_SIZES = [128, 32, 8, 1];
+    /**
+     * Run `rows` through a multi-row `INSERT` built as `head + (tuple,)*n`,
+     * decomposed greedily into the cached batch sizes. Preserves row order.
+     */
+    runBatched(kind, head, tuple, rows) {
+        if (rows.length === 0)
+            return;
+        let i = 0;
+        for (const size of QueryBuilder.BATCH_SIZES) {
+            while (rows.length - i >= size) {
+                const key = `${kind}:${size}`;
+                let stmt = this.batchStmts.get(key);
+                if (!stmt) {
+                    stmt = this.db.prepare(head + new Array(size).fill(tuple).join(','));
+                    this.batchStmts.set(key, stmt);
+                }
+                if (size === 1) {
+                    stmt.run(...rows[i]);
+                }
+                else {
+                    const params = [];
+                    for (let r = 0; r < size; r++) {
+                        const row = rows[i + r];
+                        for (let c = 0; c < row.length; c++)
+                            params.push(row[c]);
+                    }
+                    stmt.run(...params);
+                }
+                i += size;
+            }
+        }
+    }
     constructor(db) {
         this.db = db;
     }
+    /**
+     * Swap the underlying connection in place. Used by pool workers'
+     * connection recycling: a long-lived read connection pins WAL checkpoint
+     * progress; workers close and reopen at the pool-idle boundary.
+     */
+    rebind(db) {
+        this.db = db;
+        this.stmts = {};
+        this.batchStmts.clear();
+    }
     /** Attach a versioned OHOS API db for federated symbol lookup. */
     attachOhosApiDb(dbPath) {
         if (dbPath === this.ohosApiDbPath)
@@ -210,20 +255,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
@@ -280,34 +325,68 @@ class QueryBuilder {
             }
         })();
     }
+    /**
+     * Store one file's whole extraction bundle — nodes, edges, unresolved refs,
+     * and the file record — in a SINGLE transaction. The bulk-index path calls
+     * this once per file instead of opening one transaction per table (#1015
+     * file-order commit discipline is unchanged: callers still invoke it in file
+     * order, and row order within is input order).
+     *
+     * Edges MUST already be endpoint-filtered by the caller (the store path
+     * filters to the file's own inserted node ids), so the per-file existence
+     * SELECT that insertEdges() pays is skipped here.
+     */
+    storeFileBundle(bundle) {
+        this.db.transaction(() => {
+            this.insertNodes(bundle.nodes);
+            if (bundle.edges.length > 0) {
+                const rows = [];
+                for (const edge of bundle.edges) {
+                    rows.push([
+                        edge.source,
+                        edge.target,
+                        edge.kind,
+                        edge.metadata ? JSON.stringify(edge.metadata) : null,
+                        edge.line ?? null,
+                        edge.column ?? null,
+                        edge.provenance ?? null,
+                    ]);
+                }
+                this.runBatched('insertEdges', 'INSERT OR IGNORE INTO edges (source, target, kind, metadata, line, col, provenance) VALUES ', '(?,?,?,?,?,?,?)', rows);
+            }
+            if (bundle.refs.length > 0)
+                this.insertUnresolvedRefsBatch(bundle.refs);
+            this.upsertFile(bundle.file);
+        })();
+    }
     /**
      * Update an existing node
      */
     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
@@ -439,12 +518,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;
@@ -456,7 +535,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]));
@@ -616,15 +695,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();
@@ -651,13 +730,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();
@@ -688,21 +767,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);
@@ -957,10 +1036,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];
@@ -1099,11 +1178,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) {
@@ -1134,21 +1213,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;
@@ -1222,10 +1301,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) {
@@ -1256,10 +1335,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) {
@@ -1295,10 +1374,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)
@@ -1330,9 +1409,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({
@@ -1459,12 +1538,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);
@@ -1476,12 +1555,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);
@@ -1497,13 +1576,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 => ({
@@ -1520,10 +1599,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;
@@ -1536,17 +1615,17 @@ 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)
+        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.run({
@@ -1620,9 +1699,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({
@@ -1709,7 +1788,7 @@ class QueryBuilder {
      */
     getUnresolvedReferencesBatch(offset, limit) {
         if (!this.stmts.getUnresolvedBatch) {
-            this.stmts.getUnresolvedBatch = this.db.prepare("SELECT * FROM unresolved_refs WHERE status = 'pending' LIMIT ? OFFSET ?");
+            this.stmts.getUnresolvedBatch = this.db.prepare("SELECT * FROM unresolved_refs WHERE status = 'pending' ORDER BY rowid LIMIT ? OFFSET ?");
         }
         const rows = this.stmts.getUnresolvedBatch.all(limit, offset);
         return rows.map((row) => ({
@@ -1721,6 +1800,32 @@ class QueryBuilder {
             candidates: row.candidates ? (0, utils_1.safeJsonParse)(row.candidates, undefined) : undefined,
             filePath: row.file_path,
             language: row.language,
+            rowId: row.id,
+        }));
+    }
+    /**
+     * Keyset variant of {@link getUnresolvedReferencesBatch} for the batched
+     * resolution loop: seek past the last-seen row id instead of OFFSET-walking.
+     * OFFSET reads re-scan the accumulated failed-row prefix on every batch —
+     * O(failed rows) per read, measured at 54.6s of the kernel-scale batch loop
+     * (§7a.2) — while the seek is O(batch) forever. `id` is the rowid alias, so
+     * the enumeration order is identical to the OFFSET reader's.
+     */
+    getUnresolvedReferencesBatchAfter(afterRowId, limit) {
+        if (!this.stmts.getUnresolvedBatchAfter) {
+            this.stmts.getUnresolvedBatchAfter = this.db.prepare("SELECT * FROM unresolved_refs WHERE status = 'pending' AND id > ? ORDER BY id LIMIT ?");
+        }
+        const rows = this.stmts.getUnresolvedBatchAfter.all(afterRowId, limit);
+        return rows.map((row) => ({
+            fromNodeId: row.from_node_id,
+            referenceName: row.reference_name,
+            referenceKind: row.reference_kind,
+            line: row.line,
+            column: row.col,
+            candidates: row.candidates ? (0, utils_1.safeJsonParse)(row.candidates, undefined) : undefined,
+            filePath: row.file_path,
+            language: row.language,
+            rowId: row.id,
         }));
     }
     /**
@@ -1759,14 +1864,16 @@ class QueryBuilder {
      */
     markReferencesFailed(refs) {
         if (refs.length === 0)
-            return;
+            return 0;
         const stmt = this.db.prepare("UPDATE unresolved_refs SET status = 'failed', name_tail = ? WHERE from_node_id = ? AND reference_name = ? AND reference_kind = ?");
+        let changed = 0;
         const markMany = this.db.transaction((items) => {
             for (const ref of items) {
-                stmt.run(referenceNameTail(ref.referenceName), ref.fromNodeId, ref.referenceName, ref.referenceKind);
+                changed += stmt.run(referenceNameTail(ref.referenceName), ref.fromNodeId, ref.referenceName, ref.referenceKind).changes;
             }
         });
         markMany(refs);
+        return changed;
     }
     /**
      * Delete unresolved-ref rows by row id — the precise cleanup for refs a
@@ -1778,12 +1885,25 @@ class QueryBuilder {
      */
     deleteReferencesByRowIds(rowIds) {
         if (rowIds.length === 0)
-            return;
-        for (let i = 0; i < rowIds.length; i += SQLITE_PARAM_CHUNK_SIZE) {
-            const chunk = rowIds.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
-            const placeholders = chunk.map(() => '?').join(',');
-            this.db.prepare(`DELETE FROM unresolved_refs WHERE id IN (${placeholders})`).run(...chunk);
-        }
+            return 0;
+        let changed = 0;
+        this.db.transaction(() => {
+            for (let i = 0; i < rowIds.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+                const chunk = rowIds.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+                if (chunk.length === SQLITE_PARAM_CHUNK_SIZE) {
+                    if (!this.stmts.deleteRefsByRowIdsFull) {
+                        const placeholders = new Array(SQLITE_PARAM_CHUNK_SIZE).fill('?').join(',');
+                        this.stmts.deleteRefsByRowIdsFull = this.db.prepare(`DELETE FROM unresolved_refs WHERE id IN (${placeholders})`);
+                    }
+                    changed += this.stmts.deleteRefsByRowIdsFull.run(...chunk).changes;
+                }
+                else {
+                    const placeholders = chunk.map(() => '?').join(',');
+                    changed += this.db.prepare(`DELETE FROM unresolved_refs WHERE id IN (${placeholders})`).run(...chunk).changes;
+                }
+            }
+        })();
+        return changed;
     }
     /**
      * Park refs as status='failed' by row id — the precise counterpart of
@@ -1795,14 +1915,16 @@ class QueryBuilder {
      */
     markReferencesFailedByRowIds(refs) {
         if (refs.length === 0)
-            return;
+            return 0;
         const stmt = this.db.prepare("UPDATE unresolved_refs SET status = 'failed', name_tail = ? WHERE id = ?");
+        let changed = 0;
         const markMany = this.db.transaction((items) => {
             for (const ref of items) {
-                stmt.run(referenceNameTail(ref.referenceName), ref.rowId);
+                changed += stmt.run(referenceNameTail(ref.referenceName), ref.rowId).changes;
             }
         });
         markMany(refs);
+        return changed;
     }
     /**
      * Failed refs whose name tail matches one of the given symbol names — the
@@ -1919,7 +2041,7 @@ class QueryBuilder {
         // this file. The internal resolution path uses deleteSpecificResolvedReferences
         // instead, but QueryBuilder is part of the public API, so a library consumer
         // passing more ids than SQLITE_MAX_VARIABLE_NUMBER (32766 on the bundled
-        // node:sqlite) would otherwise hit "too many SQL variables". (#540, #1001)
+        // SQLite would otherwise hit "too many SQL variables". (#540, #1001)
         for (let i = 0; i < fromNodeIds.length; i += SQLITE_PARAM_CHUNK_SIZE) {
             const chunk = fromNodeIds.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
             const placeholders = chunk.map(() => '?').join(',');
@@ -1932,14 +2054,16 @@ class QueryBuilder {
      */
     deleteSpecificResolvedReferences(refs) {
         if (refs.length === 0)
-            return;
+            return 0;
         const stmt = this.db.prepare('DELETE FROM unresolved_refs WHERE from_node_id = ? AND reference_name = ? AND reference_kind = ?');
+        let changed = 0;
         const deleteMany = this.db.transaction((items) => {
             for (const ref of items) {
-                stmt.run(ref.fromNodeId, ref.referenceName, ref.referenceKind);
+                changed += stmt.run(ref.fromNodeId, ref.referenceName, ref.referenceKind).changes;
             }
         });
         deleteMany(refs);
+        return changed;
     }
     // ===========================================================================
     // Statistics
@@ -1961,11 +2085,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