@saluzi/codegraph 0.1.0 → 0.2.1

package/dist/db/queries.js

@@ -9,6 +9,42 @@ exports.QueryBuilder = void 0;
 const utils_1 = require("../utils");
 const query_utils_1 = require("../search/query-utils");
 const query_parser_1 = require("../search/query-parser");
+const generated_detection_1 = require("../extraction/generated-detection");
+const identifier_segments_1 = require("../search/identifier-segments");
+/**
+ * Path-only heuristic for files that should not be candidates for
+ * "dominant file" detection: test/spec files and tool-generated files.
+ * Generated files (`*.pb.go`, `*.pulsar.go`, mock outputs, …) often
+ * have huge in-file edge counts that dwarf the real source — etcd's
+ * `rpc.pb.go` has 4× the in-file edges of `server.go`.
+ */
+function isLowValueFile(filePath) {
+    const lp = filePath.toLowerCase();
+    return (/(?:^|\/)(tests?|__tests?__|spec)\//.test(lp) ||
+        /_test\.go$/.test(lp) ||
+        /(?:^|\/)test_[^/]+\.py$/.test(lp) ||
+        /_test\.py$/.test(lp) ||
+        /_spec\.rb$/.test(lp) ||
+        /_test\.rb$/.test(lp) ||
+        /\.(test|spec)\.[jt]sx?$/.test(lp) ||
+        /(test|spec|tests)\.(java|kt|scala)$/.test(lp) ||
+        /(tests?|spec)\.cs$/.test(lp) ||
+        /tests?\.swift$/.test(lp) ||
+        /_test\.dart$/.test(lp) ||
+        (0, generated_detection_1.isGeneratedFile)(filePath));
+}
+const SQLITE_PARAM_CHUNK_SIZE = 500;
+/**
+ * Last segment of a (possibly dotted/qualified) reference name — the part a
+ * new symbol's plain node name could match: 'util.greet' → 'greet',
+ * 'mod::fn' → 'fn', 'greet' → 'greet'. Written to unresolved_refs.name_tail
+ * when a ref is marked failed, so the #1240 retry lookup can match dotted
+ * refs against newly-added node names.
+ */
+function referenceNameTail(referenceName) {
+    const idx = Math.max(referenceName.lastIndexOf('.'), referenceName.lastIndexOf(':'));
+    return idx >= 0 ? referenceName.slice(idx + 1) : referenceName;
+}
 /**
  * Convert database row to Node object
  */
@@ -33,6 +69,7 @@ function rowToNode(row) {
         isAbstract: row.is_abstract === 1,
         decorators: row.decorators ? (0, utils_1.safeJsonParse)(row.decorators, undefined) : undefined,
         typeParameters: row.type_parameters ? (0, utils_1.safeJsonParse)(row.type_parameters, undefined) : undefined,
+        returnType: row.return_type ?? undefined,
         updatedAt: row.updated_at,
     };
 }
@@ -70,14 +107,34 @@ function rowToFileRecord(row) {
  */
 class QueryBuilder {
     db;
+    // Project-name tokens (go.mod / package.json / repo dir), normalized. A query
+    // word matching one is dropped from path-relevance scoring — it names the
+    // whole project, not a symbol, so it carries no discriminative signal (#720).
+    // Set once by the CodeGraph instance; empty by default (no down-weighting).
+    projectNameTokens = new Set();
     // Node cache for frequently accessed nodes (LRU-style, max 1000 entries)
     nodeCache = new Map();
     maxCacheSize = 1000;
     // Prepared statements (lazily initialized)
     stmts = {};
+    // Names whose segments were already written this session — skips re-splitting
+    // and re-inserting for the same-named nodes that repeat across files ("get",
+    // "render", …). Purely a write-path fast path; INSERT OR IGNORE is the
+    // correctness backstop. Bounded so a pathological repo can't grow it forever.
+    segmentedNames = new Set();
+    static MAX_SEGMENTED_NAMES = 65536;
     constructor(db) {
         this.db = db;
     }
+    /** Set the normalized project-name tokens used to down-weight non-discriminative
+     * query words in path scoring (#720). Called once when the project opens. */
+    setProjectNameTokens(tokens) {
+        this.projectNameTokens = tokens;
+    }
+    /** The normalized project-name tokens (#720); empty if none were derived. */
+    getProjectNameTokens() {
+        return this.projectNameTokens;
+    }
     // ===========================================================================
     // Node Operations
     // ===========================================================================
@@ -92,13 +149,13 @@ class QueryBuilder {
           start_line, end_line, start_column, end_column,
           docstring, signature, visibility,
           is_exported, is_async, is_static, is_abstract,
-          decorators, type_parameters, updated_at
+          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, @updatedAt
+          @decorators, @typeParameters, @returnType, @updatedAt
         )
       `);
         }
@@ -138,8 +195,42 @@ class QueryBuilder {
             isAbstract: node.isAbstract ? 1 : 0,
             decorators: node.decorators ? JSON.stringify(node.decorators) : null,
             typeParameters: node.typeParameters ? JSON.stringify(node.typeParameters) : null,
+            returnType: node.returnType ?? null,
             updatedAt: node.updatedAt ?? Date.now(),
         });
+        // Segment vocabulary rides the same write path (and transaction) so it can
+        // never drift ahead of the nodes it describes. Deletes intentionally leave
+        // orphans behind — vocab rows are proposals re-verified against nodes
+        // before use, and a full index clears the table at its start. File nodes
+        // are excluded: a file's basename duplicates the symbols inside it
+        // (state-machine.ts / OrderStateMachine), which double-counts every
+        // concept and defeats the singleton-vs-cluster rarity statistics. Import
+        // nodes are excluded too (#1144): they're named after module specifiers
+        // ("external-unindexed-pkg", "./utils/helpers"), not symbols — an
+        // import-only name can never be surfaced (getSegmentMatches requires a
+        // real definition), so its rows would only inflate the rarity statistics.
+        if (this.isSegmentableKind(node.kind))
+            this.insertNameSegments(node.name);
+    }
+    /** Which node kinds contribute their name to the segment vocabulary — the
+     *  single gate shared by insertNode, updateNode, and the rebuild page query
+     *  (getDistinctNodeNames), so the write paths can't drift apart. */
+    isSegmentableKind(kind) {
+        return kind !== 'file' && kind !== 'import';
+    }
+    /** Write `name`'s segments into name_segment_vocab (idempotent). */
+    insertNameSegments(name) {
+        if (this.segmentedNames.has(name))
+            return;
+        if (this.segmentedNames.size >= QueryBuilder.MAX_SEGMENTED_NAMES)
+            this.segmentedNames.clear();
+        this.segmentedNames.add(name);
+        if (!this.stmts.insertNameSegment) {
+            this.stmts.insertNameSegment = this.db.prepare('INSERT OR IGNORE INTO name_segment_vocab (segment, name) VALUES (?, ?)');
+        }
+        for (const segment of (0, identifier_segments_1.splitIdentifierSegments)(name)) {
+            this.stmts.insertNameSegment.run(segment, name);
+        }
     }
     /**
      * Insert multiple nodes in a transaction
@@ -176,6 +267,7 @@ class QueryBuilder {
           is_abstract = @isAbstract,
           decorators = @decorators,
           type_parameters = @typeParameters,
+          return_type = @returnType,
           updated_at = @updatedAt
         WHERE id = @id
       `);
@@ -207,8 +299,19 @@ class QueryBuilder {
             isAbstract: node.isAbstract ? 1 : 0,
             decorators: node.decorators ? JSON.stringify(node.decorators) : null,
             typeParameters: node.typeParameters ? JSON.stringify(node.typeParameters) : null,
+            returnType: node.returnType ?? null,
             updatedAt: node.updatedAt ?? Date.now(),
         });
+        // updateNode is a second real write path to `nodes` — framework
+        // post-extract passes rewrite names through it (NestJS route prefixing),
+        // and a renamed node's new name must reach the segment vocabulary just
+        // like an inserted one's (#1141). Without this the rename left the new
+        // name permanently unsearchable: the old name's rows became honest-gate
+        // orphans and the only backfill is gated on the vocab being EMPTY.
+        // insertNameSegments is idempotent (in-memory set + INSERT OR IGNORE),
+        // so no name-changed check is needed.
+        if (this.isSegmentableKind(node.kind))
+            this.insertNameSegments(node.name);
     }
     /**
      * Delete a node by ID
@@ -236,6 +339,86 @@ class QueryBuilder {
         }
         this.stmts.deleteNodesByFile.run(filePath);
     }
+    // ===========================================================================
+    // Name-segment vocabulary (prompt-hook graph-derived gate)
+    // ===========================================================================
+    /** Wipe the segment vocabulary. A full index calls this at its start; the
+     *  node write path repopulates it as files (re-)index, so the end state is
+     *  exactly the current names with no orphan rows. */
+    clearNameSegmentVocab() {
+        this.db.exec('DELETE FROM name_segment_vocab');
+        this.segmentedNames.clear();
+    }
+    /** True when the vocab has no rows — an index built before the table existed.
+     *  `sync` uses this to heal such databases (see rebuildNameSegmentVocabFrom). */
+    isNameSegmentVocabEmpty() {
+        const row = this.db.prepare('SELECT 1 FROM name_segment_vocab LIMIT 1').get();
+        return row === undefined;
+    }
+    /** One page of distinct segmentable node names, for batched vocab rebuilds
+     *  (file basenames and import specifiers are excluded from the vocab — see
+     *  insertNode). */
+    getDistinctNodeNames(limit, offset) {
+        const rows = this.db
+            .prepare("SELECT DISTINCT name FROM nodes WHERE kind NOT IN ('file', 'import') ORDER BY name LIMIT ? OFFSET ?")
+            .all(limit, offset);
+        return rows.map((r) => r.name);
+    }
+    /** Insert segments for a batch of names in one transaction (vocab heal path). */
+    insertNameSegmentsBatch(names) {
+        this.db.transaction(() => {
+            for (const name of names)
+                this.insertNameSegments(name);
+        })();
+    }
+    /**
+     * Names whose segments cover at least `minWords` distinct PROMPT WORDS —
+     * the co-occurrence probe behind the prompt hook's medium tier: the words
+     * "state" and "machine" both being segments of `OrderStateMachine` is strong
+     * evidence the prompt names that symbol in prose. Ordered by coverage.
+     *
+     * Takes (segment variant → original word) pairs and folds variants back to
+     * their word INSIDE the SQL: a name matching both `service` and `services`
+     * counts ONE word, not two. Counting raw variants let plural-variant pairs
+     * of a single word tie with genuine two-word matches and — because ORDER
+     * BY/LIMIT run here, before any JS-side re-check — crowd a real match past
+     * the LIMIT on vocab-heavy repos (#1146).
+     */
+    getSegmentCoOccurrence(variants, minWords, limit) {
+        if (variants.length === 0)
+            return [];
+        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
+         LIMIT ?`)
+            .all(...variants.flatMap((v) => [v.segment, v.word]), ...variants.map((v) => v.segment), minWords, limit);
+        return rows;
+    }
+    /** How many distinct names each segment appears in — the rarity signal that
+     *  separates a discriminative word ("checkout") from a ubiquitous one ("state"). */
+    getSegmentNameCounts(segments) {
+        if (segments.length === 0)
+            return new Map();
+        const placeholders = segments.map(() => '?').join(', ');
+        const rows = this.db
+            .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]));
+    }
+    /** Names containing the given segment (rare-single-word tier). */
+    getNamesForSegment(segment, limit) {
+        const rows = this.db
+            .prepare('SELECT name FROM name_segment_vocab WHERE segment = ? ORDER BY length(name) ASC LIMIT ?')
+            .all(segment, limit);
+        return rows.map((r) => r.name);
+    }
     /**
      * Get a node by ID
      */
@@ -297,9 +480,8 @@ class QueryBuilder {
         // Chunk under SQLite's parameter limit (default 999, raised to 32766
         // in better-sqlite3 builds — chunk at 500 for safety across both
         // backends and to keep the query plan simple).
-        const CHUNK = 500;
-        for (let i = 0; i < misses.length; i += CHUNK) {
-            const chunk = misses.slice(i, i + CHUNK);
+        for (let i = 0; i < misses.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = misses.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
             const placeholders = chunk.map(() => '?').join(',');
             const rows = this.db
                 .prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`)
@@ -312,6 +494,23 @@ class QueryBuilder {
         }
         return out;
     }
+    getExistingNodeIds(ids) {
+        const out = new Set();
+        if (ids.length === 0)
+            return out;
+        const uniqueIds = [...new Set(ids)];
+        for (let i = 0; i < uniqueIds.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = uniqueIds.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT id FROM nodes WHERE id IN (${placeholders})`)
+                .all(...chunk);
+            for (const row of rows) {
+                out.add(row.id);
+            }
+        }
+        return out;
+    }
     /**
      * Add a node to the cache, evicting oldest if needed
      */
@@ -341,6 +540,153 @@ class QueryBuilder {
         const rows = this.stmts.getNodesByFile.all(filePath);
         return rows.map(rowToNode);
     }
+    /**
+     * Find the file that holds the densest concentration of the project's
+     * internal call graph — the "core" file. Used by context-builder to
+     * boost ranking of symbols in that file's directory (so e.g. sinatra
+     * queries surface `lib/sinatra/base.rb`'s `route!` instead of
+     * `sinatra-contrib/lib/sinatra/multi_route.rb`'s `route` extension).
+     *
+     * Returns null if no file has a meaningful concentration (e.g. spread
+     * evenly across many files, or empty index).
+     *
+     * "Internal" = source and target are in the same file. Cross-file
+     * edges aren't useful here — they don't tell us which file is the
+     * functional center.
+     *
+     * Excludes test/spec files from candidacy via path-pattern. The agent's
+     * typical question is "how does X work", not "how is X tested", so
+     * boosting a test file's directory would be a misfire.
+     */
+    getDominantFile() {
+        if (!this.stmts.getDominantFile) {
+            // Pull top 20 candidates; we then filter out test/generated files
+            // in code (regex-grade matching that SQL LIKE can't express). The
+            // generated-file filter is critical — without it, etcd's
+            // `api/etcdserverpb/rpc.pb.go` (1916 in-file edges, generated
+            // 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
+      `);
+        }
+        const rows = this.stmts.getDominantFile.all();
+        const filtered = rows.filter(r => !isLowValueFile(r.file_path));
+        if (filtered.length === 0 || filtered[0].edge_count < 20)
+            return null;
+        return {
+            filePath: filtered[0].file_path,
+            edgeCount: filtered[0].edge_count,
+            nextEdgeCount: filtered[1]?.edge_count ?? 0,
+        };
+    }
+    /**
+     * Find the file that holds the densest concentration of the project's
+     * `route` nodes (framework-emitted: Express/Gin/Flask/Rails/Drupal/etc.).
+     * Used by handleContext on small repos to inline the project's routing
+     * config when the agent's query is about request flow — eliminating the
+     * "Glob + Read routes.rb" pattern that beats codegraph on tiny realworld
+     * template repos.
+     *
+     * Excludes test/generated files from candidacy. Returns null if there
+     * are fewer than 3 non-test routes total, or if no file holds at least
+     * 30% of them (diffuse routing → no single answer file).
+     */
+    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
+      `);
+        }
+        const rows = this.stmts.getTopRouteFile.all();
+        const filtered = rows.filter(r => !isLowValueFile(r.file_path));
+        if (filtered.length === 0)
+            return null;
+        const totalRoutes = filtered.reduce((sum, r) => sum + r.cnt, 0);
+        const top = filtered[0];
+        if (totalRoutes < 3 || top.cnt < 3)
+            return null;
+        if (top.cnt / totalRoutes < 0.30)
+            return null;
+        return { filePath: top.file_path, routeCount: top.cnt, totalRoutes };
+    }
+    /**
+     * Build a URL → handler manifest from the index. Each route node's
+     * `references` edge points at the function/method that handles the
+     * request. We join them in one pass; the agent gets the canonical
+     * routing answer ("POST /users/login → AuthController#login") without
+     * having to parse the framework's route DSL itself.
+     *
+     * Also returns the file with the most handler endpoints — used as the
+     * "top handler file" to inline source for, so the agent has both the
+     * mapping AND the handler implementations.
+     */
+    getRoutingManifest(limit = 40) {
+        if (!this.stmts.getRoutingManifest) {
+            // 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 ?
+      `);
+        }
+        const rows = this.stmts.getRoutingManifest.all(limit);
+        // Drop test/generated handlers — same hygiene as elsewhere.
+        const filtered = rows.filter(r => !isLowValueFile(r.handler_file));
+        if (filtered.length < 3)
+            return null;
+        // Identify the file holding the most handlers (the "primary handler file").
+        const fileCounts = new Map();
+        for (const r of filtered) {
+            fileCounts.set(r.handler_file, (fileCounts.get(r.handler_file) ?? 0) + 1);
+        }
+        let topHandlerFile = null;
+        let topHandlerFileCount = 0;
+        for (const [file, count] of fileCounts) {
+            if (count > topHandlerFileCount) {
+                topHandlerFile = file;
+                topHandlerFileCount = count;
+            }
+        }
+        return {
+            entries: filtered.map(r => ({
+                url: r.url,
+                handler: r.handler,
+                handlerFile: r.handler_file,
+                handlerLine: r.handler_line,
+                handlerKind: r.handler_kind,
+            })),
+            topHandlerFile,
+            topHandlerFileCount,
+            totalRoutes: filtered.length,
+        };
+    }
     /**
      * Get all nodes of a specific kind
      */
@@ -351,6 +697,21 @@ class QueryBuilder {
         const rows = this.stmts.getNodesByKind.all(kind);
         return rows.map(rowToNode);
     }
+    /**
+     * Stream every node of a kind one at a time (lazy) instead of materializing
+     * them all like {@link getNodesByKind}. For unbounded kinds (`function`,
+     * `method`) on a symbol-dense project the full array is gigabytes; the
+     * dynamic-edge synthesizers only scan-and-filter, so they iterate to keep
+     * memory O(1) in the node count rather than O(nodes) (#610).
+     */
+    *iterateNodesByKind(kind) {
+        // Fresh statement per call (not a cached one): an iterator holds an open
+        // cursor, so a shared statement would conflict across overlapping scans.
+        const stmt = this.db.prepare('SELECT * FROM nodes WHERE kind = ?');
+        for (const row of stmt.iterate(kind)) {
+            yield rowToNode(row);
+        }
+    }
     /**
      * Get all nodes in the database
      */
@@ -358,6 +719,33 @@ class QueryBuilder {
         const rows = this.db.prepare('SELECT * FROM nodes').all();
         return rows.map(rowToNode);
     }
+    /**
+     * Stream nodes of one language whose `decorators` JSON array contains
+     * `decorator`. The LIKE on the JSON text is a cheap index-free pre-filter
+     * (a decorator name can appear as a substring of another), so callers must
+     * still exact-check `node.decorators.includes(decorator)`. Exists so the
+     * kotlin expect/actual synthesizer never materializes the whole node table
+     * the way `getAllNodes().filter(...)` did — that array alone OOM'd Node's
+     * default heap on a 2M-node graph (#1212).
+     */
+    *iterateNodesByLanguageWithDecorator(language, decorator) {
+        // Fresh statement per call — an iterator holds an open cursor (see
+        // iterateNodesByKind).
+        const stmt = this.db.prepare("SELECT * FROM nodes WHERE language = ? AND decorators LIKE '%' || ? || '%'");
+        for (const row of stmt.iterate(language, `"${decorator}"`)) {
+            yield rowToNode(row);
+        }
+    }
+    /**
+     * Distinct languages present in the files table. One indexed aggregate —
+     * lets the dynamic-edge synthesizers skip passes for languages the project
+     * doesn't contain at all (a Kotlin pass has no work on a pure-C repo), so
+     * their cost is zero rather than a full-graph scan that finds nothing (#1212).
+     */
+    getDistinctFileLanguages() {
+        const rows = this.db.prepare('SELECT DISTINCT language FROM files').all();
+        return new Set(rows.map((r) => r.language));
+    }
     /**
      * Get nodes by exact name match (uses idx_nodes_name index)
      */
@@ -368,6 +756,17 @@ class QueryBuilder {
         const rows = this.stmts.getNodesByName.all(name);
         return rows.map(rowToNode);
     }
+    /**
+     * Nodes whose name starts with `prefix`, by index range scan (a LIKE would
+     * skip idx_nodes_name under SQLite's default case-insensitive LIKE).
+     */
+    getNodesByNamePrefix(prefix, limit = 20) {
+        if (!this.stmts.getNodesByNamePrefix) {
+            this.stmts.getNodesByNamePrefix = this.db.prepare('SELECT * FROM nodes WHERE name >= ? AND name < ? ORDER BY name LIMIT ?');
+        }
+        const rows = this.stmts.getNodesByNamePrefix.all(prefix, prefix + '￿', limit);
+        return rows.map(rowToNode);
+    }
     /**
      * Get nodes by exact qualified name match (uses idx_nodes_qualified_name index)
      */
@@ -418,10 +817,7 @@ class QueryBuilder {
         const text = parsed.text;
         const kinds = mergedKinds;
         const languages = mergedLanguages;
-        // Detect CJK content in query for specialised search path
-        const cjkPattern = /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/;
-        const hasCJK = text ? cjkPattern.test(text) : false;
-        // First try FTS5 with prefix matching (best for English identifiers)
+        // 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
@@ -429,11 +825,6 @@ class QueryBuilder {
             // a smaller multiplier risks returning fewer than `limit`
             // results despite the DB having plenty of matches.
             : this.searchAllByFilters({ kinds, languages, limit: limit * 5 });
-        // If query has CJK characters and FTS found nothing (FTS5 unicode61
-        // can't tokenize CJK), search name + docstring with LIKE
-        if (results.length === 0 && hasCJK) {
-            results = this.searchNodesCJK(text, { kinds, languages, limit, offset });
-        }
         // If no FTS results, try LIKE-based substring search
         if (results.length === 0 && text.length >= 2) {
             results = this.searchNodesLike(text, { kinds, languages, limit, offset });
@@ -483,7 +874,7 @@ class QueryBuilder {
                 ...r,
                 score: r.score
                     + (0, query_utils_1.kindBonus)(r.node.kind)
-                    + (0, query_utils_1.scorePathRelevance)(r.node.filePath, scoringQuery)
+                    + (0, query_utils_1.scorePathRelevance)(r.node.filePath, scoringQuery, this.projectNameTokens)
                     + (0, query_utils_1.nameMatchBonus)(r.node.name, scoringQuery),
             }));
             results.sort((a, b) => b.score - a.score);
@@ -706,80 +1097,6 @@ class QueryBuilder {
             score: row.score,
         }));
     }
-    /**
-     * CJK-aware search using LIKE on name + docstring.
-     *
-     * FTS5 unicode61 cannot tokenize CJK characters — it treats entire CJK
-     * sequences as opaque tokens that never match. This method bypasses FTS
-     * and searches the name, qualified_name, and docstring columns directly
-     * with LIKE, matching CJK bigrams/trigrams extracted by extractSearchTerms.
-     *
-     * Scoring priority:
-     *   name match (1.0) > qualified_name (0.8) > docstring (0.6)
-     */
-    searchNodesCJK(query, options) {
-        const { kinds, languages, limit = 100, offset = 0 } = options;
-        // Extract CJK terms (bigrams, trigrams, full sequences)
-        const cjkPattern = /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]+/g;
-        const cjkTerms = new Set();
-        let m;
-        while ((m = cjkPattern.exec(query)) !== null) {
-            const text = m[0];
-            if (text.length >= 2) cjkTerms.add(text);
-            for (let i = 0; i < text.length - 1; i++) cjkTerms.add(text.slice(i, i + 2));
-            for (let i = 0; i < text.length - 2; i++) cjkTerms.add(text.slice(i, i + 3));
-        }
-        // Also extract ASCII terms for combined matching
-        const asciiTerms = query
-            .replace(cjkPattern, ' ')
-            .split(/\s+/)
-            .filter(t => t.length >= 2);
-        const allTerms = [...cjkTerms, ...asciiTerms];
-        if (allTerms.length === 0) return [];
-        // Build OR conditions: each term searches name, qualified_name, docstring
-        const whereClauses = [];
-        const whereParams = [];
-        for (const term of allTerms.slice(0, 10)) { // cap at 10 terms to avoid huge queries
-            const pattern = `%${term}%`;
-            whereClauses.push('(name LIKE ? OR qualified_name LIKE ? OR docstring LIKE ?)');
-            whereParams.push(pattern, pattern, pattern);
-        }
-        let sql = `
-      SELECT *,
-        CASE
-          WHEN name LIKE ? THEN 1.0
-          WHEN qualified_name LIKE ? THEN 0.8
-          WHEN docstring LIKE ? THEN 0.6
-          ELSE 0.4
-        END as score
-      FROM nodes
-      WHERE (${whereClauses.join(' OR ')})
-    `;
-        // First term for the CASE scoring (use the longest CJK term)
-        const primaryTerm = allTerms.reduce((a, b) => a.length >= b.length ? a : b);
-        const primaryPattern = `%${primaryTerm}%`;
-        const params = [primaryPattern, primaryPattern, primaryPattern, ...whereParams];
-        if (kinds && kinds.length > 0) {
-            sql += ` AND kind IN (${kinds.map(() => '?').join(',')})`;
-            params.push(...kinds);
-        }
-        if (languages && languages.length > 0) {
-            sql += ` AND language IN (${languages.map(() => '?').join(',')})`;
-            params.push(...languages);
-        }
-        sql += ' ORDER BY score DESC, length(name) ASC LIMIT ? OFFSET ?';
-        params.push(limit, offset);
-        try {
-            const rows = this.db.prepare(sql).all(...params);
-            return rows.map((row) => ({
-                node: rowToNode(row),
-                score: row.score,
-            }));
-        }
-        catch {
-            return [];
-        }
-    }
     /**
      * Find nodes by exact name match
      *
@@ -924,8 +1241,19 @@ class QueryBuilder {
      * Insert multiple edges in a transaction
      */
     insertEdges(edges) {
+        if (edges.length === 0)
+            return;
         this.db.transaction(() => {
+            const endpointIds = new Set();
+            for (const edge of edges) {
+                endpointIds.add(edge.source);
+                endpointIds.add(edge.target);
+            }
+            const existingNodeIds = this.getExistingNodeIds([...endpointIds]);
             for (const edge of edges) {
+                if (!existingNodeIds.has(edge.source) || !existingNodeIds.has(edge.target)) {
+                    continue;
+                }
                 this.insertEdge(edge);
             }
         })();
@@ -995,6 +1323,78 @@ class QueryBuilder {
         const rows = this.db.prepare(sql).all(...params);
         return rows.map(rowToEdge);
     }
+    /**
+     * Distinct file paths that DEPEND ON `filePath`: every file containing a
+     * symbol with a cross-file edge (any kind except `contains`) into a symbol
+     * of this file. This is the file-level projection of the symbol dependency
+     * graph and the basis for blast-radius / `affected` test selection.
+     *
+     * It deliberately does NOT restrict to `imports` edges. In this graph an
+     * `imports` edge connects a file to its own local import declarations
+     * (it is always same-file), so an imports-only lookup returns zero
+     * cross-file dependents for every file. The real cross-file dependency
+     * signal is the resolved call/reference graph — calls, references,
+     * instantiates, extends, implements, overrides, type_of, returns,
+     * decorates — exactly what {@link GraphTraverser.getImpactRadius} traverses.
+     * `contains` is excluded: a parent containing a symbol does not *depend* on
+     * 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'
+        AND src.file_path != ?`;
+        const rows = this.db.prepare(sql).all(filePath, filePath);
+        return rows.map((r) => r.fp);
+    }
+    /**
+     * Distinct file paths that `filePath` DEPENDS ON — the inverse of
+     * {@link getDependentFilePaths}: every file containing a symbol that a
+     * symbol of this file has a cross-file edge into. Same edge-kind rules
+     * (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'
+        AND tgt.file_path != ?`;
+        const rows = this.db.prepare(sql).all(filePath, filePath);
+        return rows.map((r) => r.fp);
+    }
+    /**
+     * Cross-file edges whose TARGET is a node in `filePath` and whose SOURCE is a
+     * node in a *different* file, paired with the target node's (name, kind) so a
+     * caller can re-resolve the edge to the re-indexed target's new ID (node IDs
+     * are `sha256(filePath:kind:name:line)`, so any line shift in the callee file
+     * changes target IDs and a naive re-insert by old ID silently drops them).
+     * Used by `storeExtractionResult` to preserve incoming edges across a file
+     * re-index (issue #899). Same edge-kind rules as
+     * {@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'
+        AND src.file_path != ?`;
+        const rows = this.db.prepare(sql).all(filePath, filePath);
+        return rows.map(row => ({
+            ...rowToEdge(row),
+            targetName: row.target_name,
+            targetKind: row.target_kind,
+            sourceFilePath: row.source_file_path,
+            sourceLanguage: row.source_language,
+        }));
+    }
     // ===========================================================================
     // File Operations
     // ===========================================================================
@@ -1059,6 +1459,16 @@ class QueryBuilder {
         const rows = this.stmts.getAllFiles.all();
         return rows.map(rowToFileRecord);
     }
+    /**
+     * Most recent index timestamp (ms since epoch) across all tracked files, or
+     * null when nothing is indexed yet. One indexed aggregate, no per-row scan. (#329)
+     */
+    getLastIndexedAt() {
+        const row = this.db
+            .prepare('SELECT MAX(indexed_at) AS last FROM files')
+            .get();
+        return row?.last ?? null;
+    }
     /**
      * Get files that need re-indexing (hash changed)
      */
@@ -1151,22 +1561,28 @@ class QueryBuilder {
         }));
     }
     /**
-     * Get the count of unresolved references without loading them into memory
+     * Get the count of PENDING (never-attempted) references without loading
+     * them into memory. Rows marked status='failed' — attempted by a completed
+     * pass, no match — are excluded: they are not outstanding work, only retry
+     * candidates for the #1240 sweep, so they must not trip the #1187 orphan
+     * sweep or the `status` pending-refs warning.
      */
     getUnresolvedReferencesCount() {
         if (!this.stmts.getUnresolvedCount) {
-            this.stmts.getUnresolvedCount = this.db.prepare('SELECT COUNT(*) as count FROM unresolved_refs');
+            this.stmts.getUnresolvedCount = this.db.prepare("SELECT COUNT(*) as count FROM unresolved_refs WHERE status = 'pending'");
         }
         const row = this.stmts.getUnresolvedCount.get();
         return row.count;
     }
     /**
-     * Get a batch of unresolved references using LIMIT/OFFSET pagination.
-     * Used to process references in bounded memory chunks.
+     * Get a batch of PENDING unresolved references using LIMIT/OFFSET
+     * pagination. Used to process references in bounded memory chunks; failed
+     * rows are excluded so the batched drain loop terminates once every row
+     * has been attempted.
      */
     getUnresolvedReferencesBatch(offset, limit) {
         if (!this.stmts.getUnresolvedBatch) {
-            this.stmts.getUnresolvedBatch = this.db.prepare('SELECT * FROM unresolved_refs LIMIT ? OFFSET ?');
+            this.stmts.getUnresolvedBatch = this.db.prepare("SELECT * FROM unresolved_refs WHERE status = 'pending' LIMIT ? OFFSET ?");
         }
         const rows = this.stmts.getUnresolvedBatch.all(limit, offset);
         return rows.map((row) => ({
@@ -1200,6 +1616,18 @@ class QueryBuilder {
         const rows = this.stmts.getAllNodeNames.all();
         return rows.map((r) => r.name);
     }
+    /**
+     * Stream the distinct node names one row at a time — the incremental
+     * counterpart to {@link getAllNodeNames} for callers that need to yield
+     * to the event loop mid-scan (resolver cache warm-up on multi-million-node
+     * indexes). Fresh statement per call: the iterator holds an open cursor.
+     */
+    *iterateNodeNames() {
+        const stmt = this.db.prepare('SELECT DISTINCT name FROM nodes');
+        for (const row of stmt.iterate()) {
+            yield row.name;
+        }
+    }
     /**
      * Get unresolved references scoped to specific file paths.
      * Uses the idx_unresolved_file_path index for efficient lookup.
@@ -1207,10 +1635,19 @@ class QueryBuilder {
     getUnresolvedReferencesByFiles(filePaths) {
         if (filePaths.length === 0)
             return [];
-        const placeholders = filePaths.map(() => '?').join(',');
-        const rows = this.db
-            .prepare(`SELECT * FROM unresolved_refs WHERE file_path IN (${placeholders})`)
-            .all(...filePaths);
+        // Chunk under SQLite's parameter limit: the first sync of a very large repo
+        // passes every changed file here, which an unbounded `IN (...)` would bind
+        // as one parameter each — exceeding MAX_VARIABLE_NUMBER and aborting with
+        // "too many SQL variables". (#540)
+        const rows = [];
+        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 chunkRows = this.db
+                .prepare(`SELECT * FROM unresolved_refs WHERE status = 'pending' AND file_path IN (${placeholders})`)
+                .all(...chunk);
+            rows.push(...chunkRows);
+        }
         return rows.map((row) => ({
             fromNodeId: row.from_node_id,
             referenceName: row.reference_name,
@@ -1234,15 +1671,16 @@ class QueryBuilder {
     deleteResolvedReferences(fromNodeIds) {
         if (fromNodeIds.length === 0)
             return;
-        const placeholders = fromNodeIds.map(() => '?').join(',');
-        this.db.prepare(`DELETE FROM unresolved_refs WHERE from_node_id IN (${placeholders})`).run(...fromNodeIds);
-    }
-    /**
-     * Delete unresolved refs with null/empty reference_name to prevent
-     * infinite batch loops (patched by Saluzi for v0.9.4 compatibility).
-     */
-    deleteNullReferenceNames() {
-        this.db.prepare("DELETE FROM unresolved_refs WHERE reference_name IS NULL OR reference_name = ''").run();
+        // Chunk under SQLite's parameter limit, matching every other IN-list in
+        // 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)
+        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(',');
+            this.db.prepare(`DELETE FROM unresolved_refs WHERE from_node_id IN (${placeholders})`).run(...chunk);
+        }
     }
     /**
      * Delete specific resolved references by (fromNodeId, referenceName, referenceKind) tuples.
@@ -1259,9 +1697,108 @@ class QueryBuilder {
         });
         deleteMany(refs);
     }
+    /**
+     * Mark refs a completed resolution pass could not resolve as status='failed'
+     * instead of deleting them (#1240). Failed rows are invisible to the pending
+     * count/batch readers (so drain loops and the #1187 orphan sweep still
+     * terminate) but stay queryable by name_tail so a later sync can retry them
+     * when a changed file introduces a symbol that could satisfy them. name_tail
+     * is (re)written here so rows inserted before the v8 migration get their
+     * tail the first time they're attempted.
+     */
+    markReferencesFailed(refs) {
+        if (refs.length === 0)
+            return;
+        const stmt = this.db.prepare("UPDATE unresolved_refs SET status = 'failed', name_tail = ? WHERE from_node_id = ? AND reference_name = ? AND reference_kind = ?");
+        const markMany = this.db.transaction((items) => {
+            for (const ref of items) {
+                stmt.run(referenceNameTail(ref.referenceName), ref.fromNodeId, ref.referenceName, ref.referenceKind);
+            }
+        });
+        markMany(refs);
+    }
+    /**
+     * Failed refs whose name tail matches one of the given symbol names — the
+     * candidates a sync should retry after files carrying those names changed
+     * (#1240). Names matching more than `perNameCeiling` failed refs are
+     * skipped entirely: at that population a name is external/builtin noise
+     * (`get`, `map`, …) that one new definition won't resolve — the same
+     * rationale as resolution's AMBIGUOUS_NAME_CEILING (#999) — and retrying an
+     * arbitrary subset would be both wasted work and incoherent coverage.
+     */
+    getRetryableFailedReferences(names, perNameCeiling = 500) {
+        if (names.length === 0)
+            return [];
+        // Pass 1: per-tail counts, chunked under the SQLite parameter limit.
+        const retryNames = [];
+        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 name_tail, COUNT(*) as count FROM unresolved_refs WHERE status = 'failed' AND name_tail IN (${placeholders}) GROUP BY name_tail`)
+                .all(...chunk);
+            for (const row of counts) {
+                if (row.count <= perNameCeiling)
+                    retryNames.push(row.name_tail);
+            }
+        }
+        if (retryNames.length === 0)
+            return [];
+        // Pass 2: load the surviving rows.
+        const rows = [];
+        for (let i = 0; i < retryNames.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = retryNames.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const chunkRows = this.db
+                .prepare(`SELECT * FROM unresolved_refs WHERE status = 'failed' AND name_tail IN (${placeholders})`)
+                .all(...chunk);
+            rows.push(...chunkRows);
+        }
+        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,
+        }));
+    }
+    /**
+     * Distinct node names present in the given files — the symbol names a sync
+     * pass uses to look up retryable failed refs after those files changed.
+     */
+    getNodeNamesByFiles(filePaths) {
+        if (filePaths.length === 0)
+            return [];
+        const names = new Set();
+        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 name FROM nodes WHERE file_path IN (${placeholders})`)
+                .all(...chunk);
+            for (const row of rows)
+                names.add(row.name);
+        }
+        return [...names];
+    }
     // ===========================================================================
     // Statistics
     // ===========================================================================
+    /**
+     * Lightweight (nodes, edges) count snapshot. Used around an index/sync
+     * run to compute true additions across extraction + resolution +
+     * synthesis — the per-phase counter in the orchestrator only sees
+     * extraction's contribution, which is why the CLI summary under-reported
+     * the edge count (resolution + synthesizer edges were invisible).
+     */
+    getNodeAndEdgeCount() {
+        return this.db
+            .prepare('SELECT (SELECT COUNT(*) FROM nodes) AS nodes, (SELECT COUNT(*) FROM edges) AS edges')
+            .get();
+    }
     /**
      * Get graph statistics
      */