@quolu/lattice 0.69.5 → 0.71.0

package/sensor/dist/db/queries.js

@@ -5,20 +5,26 @@
  * Prepared statements for CRUD operations on the knowledge graph.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QueryBuilder = void 0;
+exports.QueryBuilder = exports.DEPRIORITIZED_NAME_BONUS_SCALE = 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`.
+ * 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`.
+ *
+ * Path patterns plus, when the caller passes the indexed set, files whose
+ * HEADER declares them generated — a `payroll.go` full of generated CRUD has
+ * exactly the same edge-density problem as `rpc.pb.go` and nothing in its name
+ * to catch it (#1500).
  */
-function isLowValueFile(filePath) {
+function isLowValueFile(filePath, generated) {
+    if (generated?.has(filePath))
+        return true;
     const lp = filePath.toLowerCase();
     return (/(?:^|\/)(tests?|__tests?__|spec)\//.test(lp) ||
         /_test\.go$/.test(lp) ||
@@ -34,6 +40,39 @@ function isLowValueFile(filePath) {
         (0, generated_detection_1.isGeneratedFile)(filePath));
 }
 const SQLITE_PARAM_CHUNK_SIZE = 500;
+/**
+ * A SQL predicate: is the node aliased `alias` a member an INTERFACE declares?
+ *
+ * `method_signature` / `property_signature` enter the graph as `method` /
+ * `property` nodes hung off their interface by a `contains` edge (#1638). They
+ * have no body and originate no behaviour, so for a structural judgement about
+ * a FILE they are the interface restated, not an extra thing the file declares.
+ * See {@link QueryBuilder.getAmbientDeclarationPathsAmong}, the one caller, for
+ * why treating them as opaque would break that rule in three places at once.
+ *
+ * Seeks `idx_edges_target_kind`, so it costs a key lookup per row rather than a
+ * join over the whole edge table.
+ */
+const IS_INTERFACE_MEMBER = (alias) => `EXISTS (
+  SELECT 1 FROM edges ce JOIN nodes owner ON owner.id = ce.source
+   WHERE ce.target = ${alias}.id AND ce.kind = 'contains' AND owner.kind = 'interface'
+)`;
+/**
+ * How much of the exact-name bonus a `deprioritize`d path keeps (#982). Damped
+ * rather than zeroed: a query that genuinely targets that tree must still rank
+ * it, the same "discount, don't erase" rule the path penalty follows.
+ *
+ * Derived rather than picked. `nameMatchBonus`'s prefix arm tops out below
+ * `10 + 30 = 40`, and a de-prioritized node also takes the -15 path penalty, so
+ * `80 * SCALE - 15 > 40` is what stops a damped WHOLE-QUERY exact match from
+ * losing to a mere prefix match. 0.75 clears it (45). Measured on a 62k-node
+ * django index: at 0.25 that invariant breaks in practice — `child`, `parent`
+ * and `method` lose rank 1 to `children`, `all_parents` and `method_decorator`
+ * — while crowd-out removal is almost flat between 0.75 and 0.5 (39 vs 40 of 88
+ * peripheral top-10 slots cleared), so a deeper discount buys little and costs
+ * the invariant. Pinned by a test.
+ */
+exports.DEPRIORITIZED_NAME_BONUS_SCALE = 0.75;
 /**
  * `edges.resolved_by` strategy names that resolve a name WITHOUT verifying
  * that any import/require/include path actually connects the two files —
@@ -79,8 +118,11 @@ const UNCORROBORATED_FILTER_LANGUAGES_SQL_LIST = [...UNCORROBORATED_FILTER_LANGU
  * 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;
+    // Erlang refs carry a written arity (`f/1`, `mod::fn/2` — #1610); the tail a
+    // new symbol's plain name could match is the arity-less function name.
+    const base = referenceName.replace(/\/\d{1,3}$/, '') || referenceName;
+    const idx = Math.max(base.lastIndexOf('.'), base.lastIndexOf(':'));
+    return idx >= 0 ? base.slice(idx + 1) : base;
 }
 /**
  * Convert database row to Node object
@@ -164,6 +206,7 @@ function rowToFileRecord(row) {
         nodeCount: row.node_count,
         extractionVersion: row.extraction_version ?? 0,
         errors: row.errors ? (0, utils_1.safeJsonParse)(row.errors, undefined) : undefined,
+        generated: row.generated === 1,
     };
 }
 /**
@@ -176,9 +219,16 @@ class QueryBuilder {
     // whole project, not a symbol, so it carries no discriminative signal (#720).
     // Set once by the LatticeSensor instance; empty by default (no down-weighting).
     projectNameTokens = new Set();
+    isDeprioritizedPath;
+    // FTS5 availability flag — detected once at construction time (#1532)
+    _fts5Available;
     // Node cache for frequently accessed nodes (LRU-style, max 1000 entries)
     nodeCache = new Map();
     maxCacheSize = 1000;
+    // getDominantFile()'s answer, tagged with the database change stamp it was
+    // computed under (see getChangeStamp). Query-independent, so one value
+    // serves every explore until the database changes (#1864).
+    dominantFileMemo;
     // Prepared statements (lazily initialized)
     stmts = {};
     // Names whose segments were already written this session — skips re-splitting
@@ -195,6 +245,11 @@ class QueryBuilder {
     // (and therefore resolution's insertion-order disambiguation) is identical
     // to the one-row-per-run path.
     batchStmts = new Map();
+    // Kind-filtered edge reads build their SQL per call (a variable IN list),
+    // but from a handful of kind sets: prepare each shape once. Supertype walks
+    // and the member-lookup passes issue them per node, and preparing cost
+    // about a third of the read.
+    edgeKindStmts = new Map();
     static BATCH_SIZES = [128, 32, 8, 1];
     /**
      * Run `rows` through a multi-row `INSERT` built as `head + (tuple,)*n`,
@@ -230,6 +285,14 @@ class QueryBuilder {
     }
     constructor(db) {
         this.db = db;
+        // Detect FTS5 availability once (#1532)
+        try {
+            db.prepare("SELECT * FROM nodes_fts LIMIT 0").get();
+            this._fts5Available = true;
+        }
+        catch {
+            this._fts5Available = false;
+        }
     }
     /**
      * Swap the underlying connection in place. Used by pool workers'
@@ -247,6 +310,21 @@ class QueryBuilder {
         this.db = db;
         this.stmts = {};
         this.batchStmts.clear();
+        this.edgeKindStmts.clear();
+        // The change stamp is per connection, and fresh connections to two
+        // different databases report the same one — the memo goes with the old
+        // connection, or a worker following a rebuilt index keeps its answer (#1864).
+        this.dominantFileMemo = undefined;
+    }
+    edgeKindStmt(sql) {
+        let stmt = this.edgeKindStmts.get(sql);
+        if (!stmt) {
+            if (this.edgeKindStmts.size >= 64)
+                this.edgeKindStmts.delete(this.edgeKindStmts.keys().next().value);
+            stmt = this.db.prepare(sql);
+            this.edgeKindStmts.set(sql, stmt);
+        }
+        return stmt;
     }
     /** Set the normalized project-name tokens used to down-weight non-discriminative
      * query words in path scoring (#720). Called once when the project opens. */
@@ -257,6 +335,19 @@ class QueryBuilder {
     getProjectNameTokens() {
         return this.projectNameTokens;
     }
+    /**
+     * Set the predicate that marks a path as de-prioritized by the project's
+     * `lattice-sensor.json` `deprioritize` patterns (#982). Ranking-only: those paths
+     * stay indexed and findable, they just stop outranking first-party code.
+     * Called once when the project opens; undefined disables the lever.
+     */
+    setDeprioritizedPathMatcher(matcher) {
+        this.isDeprioritizedPath = matcher;
+    }
+    /** The `deprioritize` predicate (#982), so other rankers apply the same lever. */
+    getDeprioritizedPathMatcher() {
+        return this.isDeprioritizedPath;
+    }
     // ===========================================================================
     // Node Operations
     // ===========================================================================
@@ -718,10 +809,16 @@ class QueryBuilder {
         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);
+            // Every edge insert checks its endpoints here, a chunk at a time: the
+            // full-size statement is prepared once, the final partial chunk ad hoc.
+            let stmt;
+            if (chunk.length === SQLITE_PARAM_CHUNK_SIZE) {
+                stmt = this.stmts.existingNodeIdsFull ??= this.db.prepare(`SELECT id FROM nodes WHERE id IN (${new Array(SQLITE_PARAM_CHUNK_SIZE).fill('?').join(',')})`);
+            }
+            else {
+                stmt = this.db.prepare(`SELECT id FROM nodes WHERE id IN (${chunk.map(() => '?').join(',')})`);
+            }
+            const rows = stmt.all(...chunk);
             for (const row of rows) {
                 out.add(row.id);
             }
@@ -747,16 +844,58 @@ class QueryBuilder {
     clearCache() {
         this.nodeCache.clear();
     }
+    /**
+     * Whether any node in `filePath` is exported — `getNodesByFile(f).some((n) =>
+     * n.isExported)` as one indexed probe, without decoding the file's nodes.
+     */
+    fileHasExportedNode(filePath) {
+        if (!this.stmts.fileHasExportedNode) {
+            this.stmts.fileHasExportedNode = this.db.prepare('SELECT 1 FROM nodes WHERE file_path = ? AND is_exported = 1 LIMIT 1');
+        }
+        return this.stmts.fileHasExportedNode.get(filePath) !== undefined;
+    }
+    /** The exported nodes of a file, in {@link getNodesByFile} order, decoding only those rows. */
+    getExportedNodesByFile(filePath) {
+        if (!this.stmts.getExportedNodesByFile) {
+            this.stmts.getExportedNodesByFile = this.db.prepare('SELECT * FROM nodes WHERE file_path = ? AND is_exported = 1 ORDER BY start_line, id');
+        }
+        return this.stmts.getExportedNodesByFile.all(filePath).map(rowToNode);
+    }
+    /** The nodes of a file with one name, in {@link getNodesByFile} order, decoding only those rows. */
+    getNodesByFileAndName(filePath, name) {
+        if (!this.stmts.getNodesByFileAndName) {
+            this.stmts.getNodesByFileAndName = this.db.prepare('SELECT * FROM nodes WHERE file_path = ? AND name = ? ORDER BY start_line, id');
+        }
+        return this.stmts.getNodesByFileAndName.all(filePath, name).map(rowToNode);
+    }
     /**
      * Get all nodes in a file
      */
     getNodesByFile(filePath) {
         if (!this.stmts.getNodesByFile) {
-            this.stmts.getNodesByFile = this.db.prepare('SELECT * FROM nodes WHERE file_path = ? ORDER BY start_line');
+            this.stmts.getNodesByFile = this.db.prepare('SELECT * FROM nodes WHERE file_path = ? ORDER BY start_line, id');
         }
         const rows = this.stmts.getNodesByFile.all(filePath);
         return rows.map(rowToNode);
     }
+    /**
+     * Get all nodes in several files at once — one chunked `IN` query rather than
+     * one {@link getNodesByFile} per file (#1975).
+     */
+    getNodesByFiles(filePaths) {
+        const unique = [...new Set(filePaths)];
+        const out = [];
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT * FROM nodes WHERE file_path IN (${placeholders})`)
+                .all(...chunk);
+            for (const row of rows)
+                out.push(rowToNode(row));
+        }
+        return out;
+    }
     /**
      * Find the file that holds the densest concentration of the project's
      * internal call graph — the "core" file. Used by context-builder to
@@ -774,8 +913,46 @@ class QueryBuilder {
      * 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.
+     *
+     * The answer depends only on the graph, never on the query, and the
+     * aggregation behind it scans every edge — seconds on a large index, paid
+     * by every generic explore (#1864). So it is memoized per database change
+     * stamp: recomputed only after something wrote to the database.
      */
     getDominantFile() {
+        // total_changes() counts writes that are later rolled back, so a result
+        // read inside a transaction could outlive a ROLLBACK under an unchanged
+        // stamp. Never keep one; `undefined` (a runtime without the getter) is
+        // treated the same way.
+        if (this.db.inTransaction !== false) {
+            this.dominantFileMemo = undefined;
+            return this.computeDominantFile();
+        }
+        const stamp = this.getChangeStamp();
+        if (this.dominantFileMemo?.stamp === stamp)
+            return this.dominantFileMemo.value;
+        const value = this.computeDominantFile();
+        this.dominantFileMemo = { stamp, value };
+        return value;
+    }
+    /**
+     * A value that differs whenever the database content may have changed
+     * since the last call, whoever changed it: `total_changes()` counts the
+     * rows this connection inserted, updated or deleted, and
+     * `PRAGMA data_version` moves when any OTHER connection — another process's
+     * sync, a CLI `lattice sensor index` beside a running MCP server — commits. Both
+     * are O(1), so no write path has to remember to invalidate anything.
+     * Coarse on purpose: any write, not just one to nodes/edges, forces a
+     * recompute, which only costs time, never a stale answer.
+     */
+    getChangeStamp() {
+        if (!this.stmts.getChangeStamp) {
+            this.stmts.getChangeStamp = this.db.prepare('SELECT total_changes() AS changes, (SELECT data_version FROM pragma_data_version) AS version');
+        }
+        const row = this.stmts.getChangeStamp.get();
+        return `${row.changes}:${row.version}`;
+    }
+    computeDominantFile() {
         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
@@ -796,7 +973,8 @@ class QueryBuilder {
       `);
         }
         const rows = this.stmts.getDominantFile.all();
-        const filtered = rows.filter(r => !isLowValueFile(r.file_path));
+        const generated = this.getGeneratedPathsAmong(rows.map(r => r.file_path));
+        const filtered = rows.filter(r => !isLowValueFile(r.file_path, generated));
         if (filtered.length === 0 || filtered[0].edge_count < 20)
             return null;
         return {
@@ -829,7 +1007,8 @@ class QueryBuilder {
       `);
         }
         const rows = this.stmts.getTopRouteFile.all();
-        const filtered = rows.filter(r => !isLowValueFile(r.file_path));
+        const generated = this.getGeneratedPathsAmong(rows.map(r => r.file_path));
+        const filtered = rows.filter(r => !isLowValueFile(r.file_path, generated));
         if (filtered.length === 0)
             return null;
         const totalRoutes = filtered.reduce((sum, r) => sum + r.cnt, 0);
@@ -859,6 +1038,9 @@ class QueryBuilder {
             this.stmts.getRoutingManifest = this.db.prepare(`
         SELECT
           r.name AS url,
+          r.id AS route_id,
+          r.file_path AS route_file,
+          r.start_line AS route_line,
           h.name AS handler,
           h.file_path AS handler_file,
           h.start_line AS handler_line,
@@ -868,14 +1050,15 @@ class QueryBuilder {
         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')
+          AND h.kind IN ('function', 'method', 'class', 'constant', 'variable')
         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));
+        const generated = this.getGeneratedPathsAmong(rows.map(r => r.handler_file));
+        const filtered = rows.filter(r => !isLowValueFile(r.handler_file, generated));
         if (filtered.length < 3)
             return null;
         // Identify the file holding the most handlers (the "primary handler file").
@@ -898,6 +1081,9 @@ class QueryBuilder {
                 handlerFile: r.handler_file,
                 handlerLine: r.handler_line,
                 handlerKind: r.handler_kind,
+                routeId: r.route_id,
+                routeFile: r.route_file,
+                routeLine: r.route_line,
             })),
             topHandlerFile,
             topHandlerFileCount,
@@ -909,7 +1095,7 @@ class QueryBuilder {
      */
     getNodesByKind(kind) {
         if (!this.stmts.getNodesByKind) {
-            this.stmts.getNodesByKind = this.db.prepare('SELECT * FROM nodes WHERE kind = ?');
+            this.stmts.getNodesByKind = this.db.prepare('SELECT * FROM nodes WHERE kind = ? ORDER BY file_path, start_line, id');
         }
         const rows = this.stmts.getNodesByKind.all(kind);
         return rows.map(rowToNode);
@@ -924,11 +1110,29 @@ class QueryBuilder {
     *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 = ?');
+        // Synthesis uses first/last-match precedence and caps: insertion order
+        // changes on sync. idx_nodes_kind streams this canonical order without
+        // materializing/sorting all of a large project's methods in memory.
+        const stmt = this.db.prepare('SELECT * FROM nodes WHERE kind = ? ORDER BY file_path, start_line, id');
         for (const row of stmt.iterate(kind)) {
             yield rowToNode(row);
         }
     }
+    /**
+     * iterateNodesByKind narrowed to some languages, in the same canonical
+     * order — the ORDER BY is total (`id` is unique), so this yields exactly the
+     * nodes a caller filtering iterateNodesByKind by language would keep, in the
+     * same sequence. A Go pass on a TypeScript monorepo otherwise materialized
+     * every method in the project to find a couple of Go ones.
+     */
+    *iterateNodesByKindIn(kind, languages) {
+        if (languages.length === 0)
+            return;
+        const stmt = this.db.prepare(`SELECT * FROM nodes WHERE kind = ? AND language IN (${languages.map(() => '?').join(', ')}) ORDER BY file_path, start_line, id`);
+        for (const row of stmt.iterate(kind, ...languages)) {
+            yield rowToNode(row);
+        }
+    }
     /**
      * Get all nodes in the database
      */
@@ -948,7 +1152,7 @@ class QueryBuilder {
     *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 '%' || ? || '%'");
+        const stmt = this.db.prepare("SELECT * FROM nodes WHERE language = ? AND decorators LIKE '%' || ? || '%' ORDER BY file_path, start_line, id");
         for (const row of stmt.iterate(language, `"${decorator}"`)) {
             yield rowToNode(row);
         }
@@ -964,11 +1168,26 @@ class QueryBuilder {
         return new Set(rows.map((r) => r.language));
     }
     /**
-     * Get nodes by exact name match (uses idx_nodes_name index)
+     * Get nodes by exact name match (uses idx_nodes_name index).
+     *
+     * This is resolution's candidate list, and the ORDER BY is load-bearing for
+     * index correctness, not cosmetic (CG-33). When a reference names a symbol
+     * that several files define and nothing disambiguates them, resolution binds
+     * to the first candidate — so without an ORDER BY the winner was decided by
+     * rowid, i.e. by the order files happened to be WRITTEN. A full index writes
+     * them in scan order; an incremental sync appends each file as it changes, so
+     * the same tree resolved to different edges depending on how the index was
+     * built, and a long-lived synced index drifted away from a rebuild of itself
+     * (measured at 4.3% of distinct edges, mostly `calls`).
+     *
+     * `(file_path, start_line)` is a property of the CODE, so both paths now pick
+     * the same candidate. The sort is paid once per distinct name per resolution
+     * run — ReferenceResolver memoizes this in its nameCache — and the population
+     * is capped by AMBIGUOUS_NAME_CEILING (#999).
      */
     getNodesByName(name) {
         if (!this.stmts.getNodesByName) {
-            this.stmts.getNodesByName = this.db.prepare('SELECT * FROM nodes WHERE name = ?');
+            this.stmts.getNodesByName = this.db.prepare('SELECT * FROM nodes WHERE name = ? ORDER BY file_path, start_line, id');
         }
         const rows = this.stmts.getNodesByName.all(name);
         return rows.map(rowToNode);
@@ -984,24 +1203,43 @@ class QueryBuilder {
         const rows = this.stmts.getNodesByNamePrefix.all(prefix, prefix + '￿', limit);
         return rows.map(rowToNode);
     }
+    /** File nodes whose basename starts with `prefix`, without a result cap. */
+    getFileNodesByNamePrefix(prefix) {
+        if (!this.stmts.getFileNodesByNamePrefix) {
+            this.stmts.getFileNodesByNamePrefix = this.db.prepare("SELECT * FROM nodes WHERE kind = 'file' AND name >= ? AND name < ? ORDER BY name");
+        }
+        const rows = this.stmts.getFileNodesByNamePrefix.all(prefix, prefix + '￿');
+        return rows.map(rowToNode);
+    }
     /**
      * Get nodes by exact qualified name match (uses idx_nodes_qualified_name index)
      */
     getNodesByQualifiedNameExact(qualifiedName) {
         if (!this.stmts.getNodesByQualifiedNameExact) {
-            this.stmts.getNodesByQualifiedNameExact = this.db.prepare('SELECT * FROM nodes WHERE qualified_name = ?');
+            this.stmts.getNodesByQualifiedNameExact = this.db.prepare('SELECT * FROM nodes WHERE qualified_name = ? ORDER BY file_path, start_line, id');
         }
         const rows = this.stmts.getNodesByQualifiedNameExact.all(qualifiedName);
         return rows.map(rowToNode);
     }
     /**
-     * Get nodes by lowercase name match (uses idx_nodes_lower_name expression index)
+     * Get nodes by name, case-insensitively (seeks the idx_nodes_lower_name
+     * expression index).
+     *
+     * The parameter is lowered in SQL rather than trusted to arrive lowered, so
+     * the lookup means the same thing whatever casing a caller hands it. Written
+     * as a bare `lower(name) = ?` it silently returned nothing for any input
+     * carrying an uppercase letter, and — because SQLite's `lower()` folds ASCII
+     * only while JavaScript's `.toLowerCase()` folds Unicode — a caller that
+     * pre-lowered in JavaScript could not match a non-ASCII name at all.
+     *
+     * Note this hardens the query, not its one caller: `matchFuzzy` still lowers
+     * in JavaScript before calling, so the non-ASCII gap remains open there.
      */
-    getNodesByLowerName(lowerName) {
+    getNodesByLowerName(name) {
         if (!this.stmts.getNodesByLowerName) {
-            this.stmts.getNodesByLowerName = this.db.prepare('SELECT * FROM nodes WHERE lower(name) = ?');
+            this.stmts.getNodesByLowerName = this.db.prepare('SELECT * FROM nodes WHERE lower(name) = lower(?)');
         }
-        const rows = this.stmts.getNodesByLowerName.all(lowerName);
+        const rows = this.stmts.getNodesByLowerName.all(name);
         return rows.map(rowToNode);
     }
     /**
@@ -1034,9 +1272,9 @@ class QueryBuilder {
         const text = parsed.text;
         const kinds = mergedKinds;
         const languages = mergedLanguages;
-        // First try FTS5 with prefix matching
+        // First try FTS5 with prefix matching (skip if FTS5 not available, #1532)
         let results = text
-            ? this.searchNodesFTS(text, { kinds, languages, limit, offset })
+            ? (this._fts5Available !== false ? 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`
@@ -1059,12 +1297,25 @@ class QueryBuilder {
         // pushing them past the FTS fetch limit before post-hoc scoring can help.
         // Use the max BM25 score as the base so the nameMatchBonus (exact=30 vs
         // prefix=20) actually differentiates them after rescoring.
+        //
+        // Whole-name equality MUST be written as `lower(name) = lower(?)` so it
+        // seeks `idx_nodes_lower_name`. The equivalent `name = ? COLLATE NOCASE`
+        // matches no index — `idx_nodes_name` is BINARY-collated and the expression
+        // index only matches the same expression — and degrades to a full table
+        // scan. The `LIMIT 20` does not rescue it: SQLite can only stop early once
+        // it has produced 20 rows, and this runs once per query term, most of which
+        // name nothing in the corpus. Measured per term on an unmatched term:
+        // 0.08ms on gin (2.5k nodes), 0.39ms on excalidraw (11k), 2.4ms on django
+        // (62k) — and growing with the corpus, where the seek is flat at ~0.002ms.
+        // Lowering the parameter in SQL rather than in JS is deliberate: SQLite's
+        // `lower()` and NOCASE both fold ASCII only, while JS `.toLowerCase()`
+        // folds Unicode, which would silently stop matching non-ASCII names.
         if (results.length > 0 && query) {
             const existingIds = new Set(results.map(r => r.node.id));
             const maxFtsScore = Math.max(...results.map(r => r.score));
             const terms = query.split(/\s+/).filter(t => t.length >= 2);
             for (const term of terms) {
-                let sql = 'SELECT * FROM nodes WHERE name = ? COLLATE NOCASE';
+                let sql = 'SELECT * FROM nodes WHERE lower(name) = lower(?)';
                 const params = [term];
                 if (kinds && kinds.length > 0) {
                     sql += ` AND kind IN (${kinds.map(() => '?').join(',')})`;
@@ -1087,13 +1338,24 @@ class QueryBuilder {
         // Apply multi-signal scoring
         if (results.length > 0 && (text || query)) {
             const scoringQuery = text || query;
-            results = results.map(r => ({
-                ...r,
-                score: r.score
-                    + (0, query_utils_1.kindBonus)(r.node.kind)
-                    + (0, query_utils_1.scorePathRelevance)(r.node.filePath, scoringQuery, this.projectNameTokens)
-                    + (0, query_utils_1.nameMatchBonus)(r.node.name, scoringQuery),
-            }));
+            results = results.map(r => {
+                // A path the project de-prioritized is saying its symbol NAMES are not
+                // the answer, so the exact-name bonus has to be damped too. The -15 path
+                // penalty alone cannot do it: the bonus is additive and larger (measured
+                // on #982's repro, a `usage()` helper sat at 74.8 vs 51.2 for the top
+                // product symbol — -15 lands at 59.8, still ahead). Damped, not zeroed,
+                // so the tree stays findable when it genuinely is what you asked for.
+                // Evaluated once and reused: the predicate stats the config file.
+                const deprioritized = this.isDeprioritizedPath?.(r.node.filePath) ?? false;
+                const nameBonus = (0, query_utils_1.nameMatchBonus)(r.node.name, scoringQuery);
+                return {
+                    ...r,
+                    score: r.score
+                        + (0, query_utils_1.kindBonus)(r.node.kind)
+                        + (0, query_utils_1.scorePathRelevance)(r.node.filePath, scoringQuery, this.projectNameTokens, deprioritized)
+                        + (deprioritized ? Math.round(nameBonus * exports.DEPRIORITIZED_NAME_BONUS_SCALE) : nameBonus),
+                };
+            });
             results.sort((a, b) => b.score - a.score);
             // Trim to requested limit after rescoring
             if (results.length > limit) {
@@ -1204,6 +1466,46 @@ class QueryBuilder {
         }
         return results;
     }
+    /** Bounded miss diagnostics, independent of relevance filters and ranking. */
+    getExploreMissDiagnostics(query) {
+        const words = [...new Set((query.match(/[\p{L}\p{N}]+/gu) ?? []).map(w => w.toLowerCase()))];
+        const checked = words.filter(w => w.length <= 64).slice(0, 16);
+        const limited = checked.length !== words.length;
+        if (checked.length === 0)
+            return { matched: [], unmatched: [], candidates: [], limited };
+        // EXISTS uses FTS postings and the segment primary key, never source scans.
+        // Vocab rows can outlive deleted definitions, so verify them against nodes.
+        const rows = this.db.prepare(`
+      WITH words(word, pattern) AS (VALUES ${checked.map(() => '(?, ?)').join(', ')})
+      SELECT word, (
+        EXISTS (SELECT 1 FROM nodes_fts WHERE nodes_fts MATCH pattern)
+        OR EXISTS (
+          SELECT 1 FROM name_segment_vocab v WHERE v.segment = word
+          AND EXISTS (SELECT 1 FROM nodes n WHERE n.name = v.name AND n.kind NOT IN ('file', 'import'))
+        )
+      ) AS matched FROM words
+    `).all(...checked.flatMap(w => [w, `{name qualified_name signature docstring} : "${w}"*`]));
+        const names = this.db.prepare(`
+      SELECT name FROM (
+        SELECT v.name FROM name_segment_vocab v
+        WHERE v.segment IN (${checked.map(() => '?').join(', ')})
+        AND EXISTS (SELECT 1 FROM nodes n WHERE n.name = v.name AND n.kind NOT IN ('file', 'import'))
+        LIMIT 12
+      )
+      UNION ALL
+      SELECT name FROM (
+        SELECT n.name FROM nodes_fts JOIN nodes n ON n.rowid = nodes_fts.rowid
+        WHERE nodes_fts MATCH ? AND n.kind NOT IN ('file', 'import')
+        LIMIT 12
+      )
+    `).all(...checked, `name : (${checked.map(w => `"${w}"*`).join(' OR ')})`);
+        return {
+            matched: rows.filter(r => r.matched).map(r => r.word),
+            unmatched: rows.filter(r => !r.matched).map(r => r.word),
+            candidates: [...new Set(names.map(r => r.name))].slice(0, 12),
+            limited,
+        };
+    }
     /**
      * FTS5 search with prefix matching
      */
@@ -1332,9 +1634,16 @@ class QueryBuilder {
         // 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.
         // Pass 1: Find files containing each queried name, identify distinctive names
+        //
+        // Both passes spell whole-name equality as `lower(name) = lower(?)` so they
+        // seek `idx_nodes_lower_name` — see the note in `searchNodes` for why the
+        // `name = ? COLLATE NOCASE` form full-scans instead. This path is the one
+        // that hurts most: it runs both passes for every symbol extracted from the
+        // query, and extraction is generous, so most of those names are absent from
+        // the corpus and never reach either LIMIT.
         const nameToFiles = new Map();
         for (const name of names) {
-            let sql = 'SELECT DISTINCT file_path FROM nodes WHERE name COLLATE NOCASE = ?';
+            let sql = 'SELECT DISTINCT file_path FROM nodes WHERE lower(name) = lower(?)';
             const params = [name];
             if (kinds && kinds.length > 0) {
                 sql += ` AND kind IN (${kinds.map(() => '?').join(',')})`;
@@ -1360,7 +1669,7 @@ class QueryBuilder {
             let sql = `
         SELECT nodes.*, 1.0 as score
         FROM nodes
-        WHERE name COLLATE NOCASE = ?
+        WHERE lower(name) = lower(?)
       `;
             const params = [name];
             if (kinds && kinds.length > 0) {
@@ -1434,6 +1743,30 @@ class QueryBuilder {
     // ===========================================================================
     // Edge Operations
     // ===========================================================================
+    /** Must run before file replacement/deletion cascades the endpoint edges. */
+    hasSynthesizedEdgesTouchingFile(filePath) {
+        const owned = "CASE WHEN json_valid(e.metadata) THEN json_extract(e.metadata, '$.synthesizedBy') END IS NOT NULL";
+        for (const endpoint of ['source', 'target']) {
+            if (this.db.prepare(`SELECT 1 FROM nodes n JOIN edges e ON e.${endpoint} = n.id
+        WHERE n.file_path = ? AND ${owned} LIMIT 1`).get(filePath))
+                return true;
+        }
+        // Wiring often lives in a third file, with neither endpoint in it.
+        return !!this.db.prepare(`SELECT 1 FROM edges e WHERE ${owned}
+      AND CASE WHEN json_valid(e.metadata) THEN json_extract(e.metadata, '$.registeredAt') END >= ?
+      AND CASE WHEN json_valid(e.metadata) THEN json_extract(e.metadata, '$.registeredAt') END < ? LIMIT 1`).get(`${filePath}:`, `${filePath};`);
+    }
+    wasSynthesisInput(filePath) {
+        return !!this.db.prepare('SELECT 1 FROM synthesis_inputs WHERE file_path = ?').get(filePath);
+    }
+    replaceSynthesisInputs(files) {
+        this.db.transaction(() => {
+            this.db.exec('DELETE FROM synthesis_inputs');
+            const insert = this.db.prepare('INSERT INTO synthesis_inputs(file_path) VALUES (?)');
+            for (const file of files)
+                insert.run(file);
+        })();
+    }
     /**
      * Insert a new edge
      */
@@ -1499,7 +1832,8 @@ class QueryBuilder {
         this.stmts.deleteEdgesBySource.run(sourceId);
     }
     /**
-     * Get outgoing edges from a node
+     * Get outgoing edges from a node. Preserve the source/kind index order
+     * (calls before imports/references), then break ties deterministically.
      */
     getOutgoingEdges(sourceId, kinds, provenance) {
         if ((kinds && kinds.length > 0) || provenance) {
@@ -1513,30 +1847,649 @@ class QueryBuilder {
                 sql += ' AND provenance = ?';
                 params.push(provenance);
             }
-            const rows = this.db.prepare(sql).all(...params);
+            sql += ' ORDER BY kind, target, line, col';
+            const rows = this.edgeKindStmt(sql).all(...params);
             return rows.map(rowToEdge);
         }
         if (!this.stmts.getEdgesBySource) {
-            this.stmts.getEdgesBySource = this.db.prepare('SELECT * FROM edges WHERE source = ?');
+            this.stmts.getEdgesBySource = this.db.prepare('SELECT * FROM edges WHERE source = ? ORDER BY kind, target, line, col');
         }
         const rows = this.stmts.getEdgesBySource.all(sourceId);
         return rows.map(rowToEdge);
     }
     /**
-     * Get incoming edges to a node
+     * Get incoming edges to a node. Kind must precede opaque source IDs:
+     * file IDs sort before function IDs, so source-first ordering lets imports
+     * displace actual calls in capped caller lists. Keep deterministic ties
+     * without changing the target/kind index's established kind precedence.
      */
     getIncomingEdges(targetId, kinds) {
         if (kinds && kinds.length > 0) {
-            const sql = `SELECT * FROM edges WHERE target = ? AND kind IN (${kinds.map(() => '?').join(',')})`;
-            const rows = this.db.prepare(sql).all(targetId, ...kinds);
+            const sql = `SELECT * FROM edges WHERE target = ? AND kind IN (${kinds.map(() => '?').join(',')}) ORDER BY kind, source, line, col`;
+            const rows = this.edgeKindStmt(sql).all(targetId, ...kinds);
             return rows.map(rowToEdge);
         }
         if (!this.stmts.getEdgesByTarget) {
-            this.stmts.getEdgesByTarget = this.db.prepare('SELECT * FROM edges WHERE target = ?');
+            this.stmts.getEdgesByTarget = this.db.prepare('SELECT * FROM edges WHERE target = ? ORDER BY kind, source, line, col');
         }
         const rows = this.stmts.getEdgesByTarget.all(targetId);
         return rows.map(rowToEdge);
     }
+    /**
+     * Outgoing edges for MANY source nodes in one query.
+     *
+     * The batch form of {@link getOutgoingEdges}. Building a nested outline needs
+     * the `contains` edges of every container in a file at once; doing that one
+     * source at a time is a query per symbol on files that have hundreds.
+     */
+    getOutgoingEdgesFrom(sourceIds, kinds) {
+        if (sourceIds.length === 0)
+            return [];
+        const unique = [...new Set(sourceIds)];
+        const out = [];
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            let sql = `SELECT * FROM edges WHERE source IN (${placeholders})`;
+            const params = [...chunk];
+            if (kinds && kinds.length > 0) {
+                sql += ` AND kind IN (${kinds.map(() => '?').join(',')})`;
+                params.push(...kinds);
+            }
+            const rows = this.db.prepare(sql).all(...params);
+            for (const row of rows)
+                out.push(rowToEdge(row));
+        }
+        return out;
+    }
+    /**
+     * Fan-in (total incoming edge count) for MANY nodes in one query.
+     *
+     * The per-node alternative — `getIncomingEdges(id).length` — is an indexed
+     * lookup each, but a symbol screen rendering a couple of hundred callees
+     * would issue a couple of hundred of them. Ids with no incoming edges are
+     * absent from the map rather than present as 0, so callers can tell "no
+     * edges" from "not asked about".
+     */
+    countIncomingEdges(ids) {
+        const out = new Map();
+        if (ids.length === 0)
+            return out;
+        const unique = [...new Set(ids)];
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(
+            // A test's request onto a route (tier-synthesizer's `test-request`)
+            // is not a production caller: forty tests hitting one endpoint must
+            // not make it a hub the Steps walk refuses to enter.
+            `SELECT target, COUNT(*) AS count FROM edges WHERE target IN (${placeholders})
+             AND (metadata IS NULL OR metadata NOT LIKE '%"synthesizedBy":"test-request"%') GROUP BY target`)
+                .all(...chunk);
+            for (const row of rows)
+                out.set(row.target, row.count);
+        }
+        return out;
+    }
+    /**
+     * Incoming edges for MANY target nodes in one query — the mirror of
+     * {@link getOutgoingEdgesFrom}. Needed wherever a whole file's inbound edges
+     * are wanted at once ("which files import anything in this one?").
+     */
+    getIncomingEdgesTo(targetIds, kinds) {
+        if (targetIds.length === 0)
+            return [];
+        const unique = [...new Set(targetIds)];
+        const out = [];
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            let sql = `SELECT * FROM edges WHERE target IN (${placeholders})`;
+            const params = [...chunk];
+            if (kinds && kinds.length > 0) {
+                sql += ` AND kind IN (${kinds.map(() => '?').join(',')})`;
+                params.push(...kinds);
+            }
+            const rows = this.db.prepare(sql).all(...params);
+            for (const row of rows)
+                out.push(rowToEdge(row));
+        }
+        return out;
+    }
+    /**
+     * Fan-out (total outgoing edge count) for MANY nodes in one query — the
+     * mirror of {@link countIncomingEdges}. Ids with no outgoing edges are absent
+     * from the map rather than present as 0.
+     */
+    countOutgoingEdges(ids) {
+        const out = new Map();
+        if (ids.length === 0)
+            return out;
+        const unique = [...new Set(ids)];
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT source, COUNT(*) AS count FROM edges WHERE source IN (${placeholders}) GROUP BY source`)
+                .all(...chunk);
+            for (const row of rows)
+                out.set(row.source, row.count);
+        }
+        return out;
+    }
+    /**
+     * Symbols nothing in the index points at — the candidate set behind the dead
+     * code list (`src/graph/dead-code.ts`).
+     *
+     * "Points at" is every edge kind EXCEPT `contains`: a class containing a
+     * method is structure, not use, and counting it would make every member look
+     * reached by its own container. A self-edge is excluded for the same reason
+     * a recursive function is not its own caller.
+     *
+     * One scan, one index probe per candidate. `NOT EXISTS` over
+     * `idx_edges_target_kind` is what keeps it that way — the alternative
+     * (`LEFT JOIN edges … GROUP BY`) builds a row per edge for the whole table
+     * before discarding all but the empty groups. Ordered by position so the
+     * answer is stable across runs and groups by file without a second sort.
+     *
+     * The result is deliberately NOT called dead code: an unreferenced symbol is
+     * a symbol with no STATIC reference, and the caller applies the exclusions
+     * (tests, generated files, overrides, unresolved names) that turn the
+     * candidate set into a claim worth making.
+     */
+    getUnreferencedNodes(kinds, limit) {
+        if (kinds.length === 0 || limit <= 0)
+            return [];
+        const placeholders = kinds.map(() => '?').join(',');
+        const rows = this.db
+            .prepare(`SELECT n.*, COALESCE(f.generated, 0) AS file_generated
+           FROM nodes n
+           LEFT JOIN files f ON f.path = n.file_path
+          WHERE n.kind IN (${placeholders})
+            AND NOT EXISTS (
+                  SELECT 1 FROM edges e
+                   WHERE e.target = n.id
+                     AND e.kind != 'contains'
+                     AND e.source != n.id
+                )
+       ORDER BY n.file_path, n.start_line, n.name
+          LIMIT ?`)
+            .all(...kinds, limit);
+        return rows.map((row) => ({ node: rowToNode(row), generated: row.file_generated === 1 }));
+    }
+    /**
+     * Which of `names` the index holds an UNRESOLVED reference to.
+     *
+     * The point is honesty about our own blind spots. A `failed` row in
+     * `unresolved_refs` records that some file referenced a name and the resolver
+     * could not decide what it meant — so a symbol with that name cannot be
+     * called unreferenced, whatever the edge table says. It is deliberately
+     * matched loosely, on the reference name AND on its tail (`util.greet` →
+     * `greet`), because the question being asked is "could this name be the one
+     * we failed to follow", and a maybe has to count as a yes.
+     *
+     * Bounded-lookup like {@link getGeneratedPathsAmong}: the caller holds a
+     * candidate list, so this is a chunked probe over `idx_unresolved_name`, not
+     * a scan of the table.
+     */
+    getUnresolvedNamesAmong(names) {
+        const unique = [...new Set(names)].filter((name) => name.length > 0);
+        const found = new Set();
+        if (unique.length === 0)
+            return found;
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT DISTINCT reference_name AS name FROM unresolved_refs
+            WHERE reference_name IN (${placeholders})
+            UNION
+           SELECT DISTINCT name_tail AS name FROM unresolved_refs
+            WHERE name_tail IN (${placeholders})`)
+                .all(...chunk, ...chunk);
+            for (const row of rows)
+                found.add(row.name);
+        }
+        return found;
+    }
+    /**
+     * Which of `nodeIds` extend or implement a type the resolver could not follow.
+     * An ancestor outside the index (`React.Component`, `stream.Transform`, a
+     * framework interface) leaves no edge, only this `extends` / `implements`
+     * row, so it is the one record that such an ancestor exists (#1973).
+     * Chunked probe over `idx_unresolved_from_node`.
+     */
+    getUnresolvedSupertypeSourcesAmong(nodeIds) {
+        const unique = [...new Set(nodeIds)];
+        const found = new Set();
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT DISTINCT from_node_id AS id FROM unresolved_refs
+            WHERE from_node_id IN (${placeholders})
+              AND reference_kind IN ('extends', 'implements')`)
+                .all(...chunk);
+            for (const row of rows)
+                found.add(row.id);
+        }
+        return found;
+    }
+    /**
+     * Which of `names` are carried by MORE THAN ONE symbol, at least one of which
+     * something points at.
+     *
+     * The false positive this exists to kill: `LatticeSensor.getTopRouteFile` calls
+     * `this.queries.getTopRouteFile()`, and the resolver — which prefers a
+     * same-name definition in the call site's own file — attaches that edge to
+     * the *calling* method. One of the two ends up with a self-edge and the other
+     * with nothing at all, and neither is unreferenced. From the edge table the
+     * mis-resolution and a genuinely unused twin are the same picture, so the
+     * claim is not made about either.
+     *
+     * Both halves of the condition are load-bearing. **More than one symbol**:
+     * a uniquely-named function that only calls itself is genuinely dead, and
+     * excluding every recursive function would gut the list. **Self-edges
+     * counted**: the self-edge IS the fingerprint of the mis-resolution above, so
+     * it has to count as evidence that this name resolves somewhere.
+     *
+     * Chunked probe over `idx_nodes_name`, bounded by the caller's candidate list.
+     */
+    getAmbiguousReferencedNames(names) {
+        const unique = [...new Set(names)].filter((name) => name.length > 0);
+        const found = new Set();
+        if (unique.length === 0)
+            return found;
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT name FROM (
+             SELECT n.name AS name,
+                    EXISTS (
+                      SELECT 1 FROM edges e
+                       WHERE e.target = n.id AND e.kind != 'contains'
+                    ) AS referenced
+               FROM nodes n
+              WHERE n.name IN (${placeholders})
+           )
+         GROUP BY name
+           HAVING COUNT(*) > 1 AND SUM(referenced) > 0`)
+                .all(...chunk);
+            for (const row of rows)
+                found.add(row.name);
+        }
+        return found;
+    }
+    /**
+     * Which of the given languages the index records an EXPORT marker for.
+     *
+     * A self-measurement, and the honest basis for a whole class of exclusion.
+     * The dead code report's strongest filter is "exported symbols may be reached
+     * from outside this repository" — and that filter silently does nothing for a
+     * language whose exports are not recorded, either because the extractor does
+     * not record them (Rust `pub`) or because the language has no such concept at
+     * all (Python, C, Ruby: the header or the module IS the surface). Rather than
+     * carry a table of which is which, ask the index: if nothing in this language
+     * is marked exported, the filter did not run, and no claim about outside
+     * reachability can be made for it.
+     *
+     * `idx_nodes_language` covers the grouping; the caller passes the handful of
+     * languages its candidates are actually in.
+     */
+    getLanguagesWithExports(languages) {
+        const unique = [...new Set(languages)].filter((language) => language.length > 0);
+        const found = new Set();
+        if (unique.length === 0)
+            return found;
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT language, MAX(is_exported) AS any_exported
+             FROM nodes
+            WHERE language IN (${placeholders})
+         GROUP BY language`)
+                .all(...chunk);
+            for (const row of rows)
+                if (row.any_exported === 1)
+                    found.add(row.language);
+        }
+        return found;
+    }
+    /**
+     * The nodes with the most DISTINCT dependents, most first.
+     *
+     * "Distinct" is the difference that matters: a helper called forty times from
+     * one function has a fan-in of 40 but exactly one dependent. This counts the
+     * second thing — the number a reader means by "N callers" — so the top of
+     * this list is the set of symbols a change actually radiates furthest from.
+     *
+     * `contains` is excluded because it is structure, not dependency: counting it
+     * would rank every file and class above the code they hold.
+     */
+    getTopDependedOn(limit) {
+        if (limit <= 0)
+            return [];
+        const rows = this.db
+            .prepare(`SELECT target AS nodeId, COUNT(DISTINCT source) AS dependents
+           FROM edges
+          WHERE kind != 'contains' AND source != target
+       GROUP BY target
+       ORDER BY dependents DESC
+          LIMIT ?`)
+            .all(limit);
+        return rows;
+    }
+    /**
+     * The graph's executable roots — files that RUN something at module level,
+     * ranked by how much of the project they set in motion.
+     *
+     * The engine records a statement at the top level of a file as an edge from
+     * the *file* node, so `src/bin/lattice-sensor.ts` calling `program.parse()` at
+     * module scope is a `calls` edge out of a `file`. That set is what makes the
+     * roots of a dependency graph visible: a library module holds definitions and
+     * runs nothing until someone imports it, while a CLI, a worker entry or a
+     * build script does its work on the way down the file. `instantiates` counts
+     * the same way — `new Server(...)` at module scope is the same act.
+     *
+     * A call made while initializing a module-level `variable` / `constant` —
+     * `const service = new Service()`, `app = FastAPI()` — is attributed to the
+     * declared name (#693), not to the file, so the file's own edges alone would
+     * miss most of what a real entry point runs. Those names are the file's
+     * top-level code too, so `tops` counts them alongside the file node.
+     *
+     * Ranking multiplies the two things an entry point does: it runs (calls), and
+     * it wires the project together (distinct other files its symbols reach). One
+     * alone is misleading — a registration table makes hundreds of module-level
+     * calls into itself, and a barrel file imports everything and runs nothing.
+     * The product puts the file that does both at the top.
+     */
+    getTopCallingFiles(limit) {
+        if (limit <= 0)
+            return [];
+        return this.db
+            .prepare(`WITH tops AS (
+             SELECT n.id AS file_id, n.id AS src
+               FROM nodes n
+              WHERE n.kind = 'file'
+             UNION ALL
+             SELECT c.source AS file_id, c.target AS src
+               FROM edges c
+               JOIN nodes f ON f.id = c.source
+               JOIN nodes v ON v.id = c.target
+              WHERE c.kind = 'contains'
+                AND f.kind = 'file'
+                AND v.kind IN ('variable', 'constant')
+         ),
+         runs AS (
+             SELECT t.file_id AS id, COUNT(*) AS calls
+               FROM tops t
+               JOIN edges e ON e.source = t.src
+              WHERE e.kind IN ('calls', 'instantiates')
+           GROUP BY t.file_id
+         ),
+         cand AS (
+             SELECT r.id AS id, n.file_path AS fp, r.calls AS calls
+               FROM runs r JOIN nodes n ON n.id = r.id
+         ),
+         wires AS (
+             SELECT sn.file_path AS fp, COUNT(DISTINCT tn.file_path) AS reaches
+               FROM edges e
+               JOIN nodes sn ON sn.id = e.source
+               JOIN nodes tn ON tn.id = e.target
+              WHERE e.kind != 'contains'
+                AND sn.file_path <> tn.file_path
+                AND sn.file_path IN (SELECT fp FROM cand)
+           GROUP BY sn.file_path
+         )
+         SELECT c.id AS nodeId,
+                c.fp AS filePath,
+                c.calls AS calls,
+                COALESCE(w.reaches, 0) AS reaches,
+                c.calls * (1 + COALESCE(w.reaches, 0)) AS score
+           FROM cand c LEFT JOIN wires w ON w.fp = c.fp
+       ORDER BY score DESC, calls DESC, filePath
+          LIMIT ?`)
+            .all(limit);
+    }
+    /**
+     * How many OTHER files depend on each of the given files.
+     *
+     * Counted through the symbols, not the file nodes: an `imports` edge points
+     * at the imported symbol, so a file node almost never receives one and
+     * counting edges into it would report every file as depended on by nobody.
+     * Same-file edges are excluded, which is what makes zero mean "nothing else
+     * in the index reaches into this file" — the honest reading of a root.
+     */
+    getFileDependentCounts(filePaths) {
+        if (filePaths.length === 0)
+            return [];
+        return this.db
+            .prepare(`SELECT tn.file_path AS filePath, COUNT(DISTINCT sn.file_path) AS dependents
+           FROM edges e
+           JOIN nodes tn ON tn.id = e.target
+           JOIN nodes sn ON sn.id = e.source
+          WHERE e.kind != 'contains'
+            AND tn.file_path IN (SELECT value FROM json_each(?))
+            AND sn.file_path <> tn.file_path
+       GROUP BY tn.file_path`)
+            .all(JSON.stringify(filePaths));
+    }
+    /**
+     * How far each of the given files reaches OUT: distinct other files its
+     * symbols touch, and how many references that is.
+     *
+     * The mirror of {@link getFileDependentCounts}, and the same reasoning about
+     * `contains` and same-file edges applies. It is driven from `nodes` rather
+     * than from `edges` so the work is proportional to the files asked about —
+     * the entry-points endpoint asks it about every test file in the index, and
+     * an edge-first plan would scan the whole table to answer a question about a
+     * tenth of it.
+     */
+    getFileReachCounts(filePaths) {
+        if (filePaths.length === 0)
+            return [];
+        return this.db
+            .prepare(`SELECT sn.file_path AS filePath,
+                COUNT(DISTINCT tn.file_path) AS reaches,
+                COUNT(*) AS refs
+           FROM nodes sn
+           JOIN edges e ON e.source = sn.id
+           JOIN nodes tn ON tn.id = e.target
+          WHERE sn.file_path IN (SELECT value FROM json_each(?))
+            AND e.kind != 'contains'
+            AND tn.file_path <> sn.file_path
+       GROUP BY sn.file_path`)
+            .all(JSON.stringify(filePaths));
+    }
+    /**
+     * The `file` nodes for the given paths, in one query.
+     *
+     * A file's own node is what makes a file row navigable, and looking it up
+     * with {@link getNodesInFile} means materialising every symbol in the file to
+     * throw all but one away.
+     */
+    getFileNodes(filePaths) {
+        if (filePaths.length === 0)
+            return [];
+        const rows = this.db
+            .prepare(`SELECT * FROM nodes
+          WHERE kind = 'file'
+            AND file_path IN (SELECT value FROM json_each(?))`)
+            .all(JSON.stringify(filePaths));
+        return rows.map(rowToNode);
+    }
+    /**
+     * Roll the whole edge table up to module granularity in one pass.
+     *
+     * The caller decides what a module IS — it hands in a file → module
+     * assignment and gets back the cross-module traffic. That split is
+     * deliberate: naming modules is a *policy* (top-level directories, a façade
+     * file kept separate, a monorepo root) that belongs where the reader lives,
+     * while grouping a million edges by it is *mechanics* that must happen in
+     * SQLite. Doing the fold in JavaScript instead means materialising every
+     * cross-file edge in memory; doing the naming in SQL means a tower of
+     * `instr`/`substr` no one can read.
+     *
+     * The assignment lands in a TEMP table with a primary key, so the join is
+     * indexed and the result set is bounded by modules², not by edges. Temp
+     * tables live in SQLite's own temp database, so this stays valid against a
+     * read-only main.
+     *
+     * Two result sets, because they need two different groupings over the same
+     * join: `links` counts edges per (module, module, kind), and `pairs` names
+     * the busiest symbol pairs behind each link (the map's tooltip). `pairs` is
+     * ranked and cut inside SQLite — the un-cut grouping is the one thing here
+     * that scales with distinct symbol names rather than with modules. Pairs are
+     * ranked by `declared` before raw count, so a link's tooltip names the
+     * symbols the source actually points at rather than whichever `has`/`get`
+     * happened to name-match most often.
+     *
+     * `declared` is the subset of a link's edges that came from something the
+     * source *writes down*: an import, a qualified name, an inheritance clause,
+     * or a call through a typed receiver. It exists because bare name matching
+     * (`resolvedBy: 'exact-match'`) is what invents cross-module links out of
+     * common method names — `run`, `push`, `finish` — and a map that lets those
+     * decide the layering puts the storage layer above the CLI.
+     */
+    aggregateModuleGraph(assignments, options) {
+        if (assignments.length === 0 || options.kinds.length === 0)
+            return { links: [], pairs: [] };
+        const CONFIDENCE = `COALESCE(json_extract(e.metadata, '$.confidence'), 1)`;
+        const DECLARED = `(json_extract(e.metadata, '$.resolvedBy') IN ('import', 'qualified-name')
+                       OR e.kind IN ('extends', 'implements')
+                       OR (json_extract(e.metadata, '$.resolvedBy') = 'instance-method'
+                           AND ${CONFIDENCE} >= 0.9))`;
+        this.db.exec('DROP TABLE IF EXISTS temp.cg_module_map');
+        this.db.exec('CREATE TEMP TABLE cg_module_map (path TEXT PRIMARY KEY, mod TEXT NOT NULL)');
+        try {
+            const insert = this.db.prepare('INSERT OR REPLACE INTO cg_module_map (path, mod) VALUES (?, ?)');
+            this.db.exec('BEGIN');
+            try {
+                for (const row of assignments)
+                    insert.run(row.filePath, row.module);
+                this.db.exec('COMMIT');
+            }
+            catch (err) {
+                this.db.exec('ROLLBACK');
+                throw err;
+            }
+            // ONE pass over the edge table. Grouping by the symbol names as well as
+            // the modules costs nothing extra in scan time — the join is what is
+            // expensive — and it buys both results from a single scan. Measured on
+            // this index inflated to 1.6M edges: 1.66s for this query against 3.0s
+            // for the module-level and name-level queries run separately, which is
+            // the difference between meeting and missing the map's cold budget on a
+            // ten-thousand-file repository.
+            const rows = this.db
+                .prepare(`SELECT ms.mod AS source, mt.mod AS target, e.kind AS kind,
+                  sn.name AS "from", tn.name AS "to",
+                  SUM(CASE WHEN ${CONFIDENCE} >= ? THEN 1 ELSE 0 END) AS count,
+                  SUM(CASE WHEN ${CONFIDENCE} >= ? AND ${DECLARED} THEN 1 ELSE 0 END) AS declared,
+                  SUM(CASE WHEN ${CONFIDENCE} <  ? THEN 1 ELSE 0 END) AS uncertain
+             FROM edges e
+             JOIN nodes sn ON sn.id = e.source
+             JOIN nodes tn ON tn.id = e.target
+             JOIN cg_module_map ms ON ms.path = sn.file_path
+             JOIN cg_module_map mt ON mt.path = tn.file_path
+            WHERE e.kind IN (SELECT value FROM json_each(?))
+              AND ms.mod <> mt.mod
+         GROUP BY ms.mod, mt.mod, e.kind, sn.name, tn.name`)
+                .all(options.minConfidence, options.minConfidence, options.minConfidence, JSON.stringify(options.kinds));
+            return foldModuleRows(rows, options);
+        }
+        finally {
+            this.db.exec('DROP TABLE IF EXISTS temp.cg_module_map');
+        }
+    }
+    /**
+     * Every ordered pair of files where one reaches into the other, once each.
+     *
+     * The input a cycle finder wants: file-level circular dependencies are the
+     * strongly connected components of this graph. One query instead of the
+     * dependency lookup per file that {@link GraphQueryManager.findCircularDependencies}
+     * does — which matters because a cycle report is only interesting on a large
+     * repo, and that is exactly where a query per file stops being affordable.
+     *
+     * `contains` is excluded (a file "contains" its own symbols, which is not a
+     * dependency), and so are same-file edges and low-confidence name matches:
+     * a cycle conjured by a common method name is a false alarm a reader cannot
+     * check.
+     */
+    getCrossFileDependencyPairs(minConfidence) {
+        return this.db
+            .prepare(`SELECT DISTINCT sn.file_path AS source, tn.file_path AS target
+           FROM edges e
+           JOIN nodes sn ON sn.id = e.source
+           JOIN nodes tn ON tn.id = e.target
+          WHERE e.kind <> 'contains'
+            AND sn.file_path <> tn.file_path
+            AND COALESCE(json_extract(e.metadata, '$.confidence'), 1) >= ?`)
+            .all(minConfidence);
+    }
+    /**
+     * Every unresolved reference recorded in one FILE, ordered by line.
+     *
+     * The per-symbol form above answers "what does this body reach that the
+     * index does not hold". A whole-file reader asks the same question of every
+     * line at once, and asking it one symbol at a time is a query per symbol —
+     * 153 of them on this repo's largest file. `unresolved_refs.file_path` is
+     * indexed, so this is one lookup whatever the file holds.
+     *
+     * `limit` bounds the answer rather than the work: the caller draws a marker
+     * per row, and a generated file with fifty thousand of them would ship
+     * megabytes to say something a count already says. Rows come back in line
+     * order, so a cap trims the END of the file, which is at least legible.
+     */
+    getUnresolvedReferencesInFile(filePath, limit = 5000) {
+        if (!this.stmts.getUnresolvedInFile) {
+            this.stmts.getUnresolvedInFile = this.db.prepare('SELECT * FROM unresolved_refs WHERE file_path = ? ORDER BY line, col LIMIT ?');
+        }
+        const rows = this.stmts.getUnresolvedInFile.all(filePath, 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,
+        }));
+    }
+    /**
+     * References recorded against a symbol that never resolved to a node — the
+     * calls and type mentions that leave the index (a third-party package, a
+     * runtime builtin, a language construct extraction doesn't model).
+     *
+     * Read-only. It exists so a reader can say "N calls into symbols outside the
+     * index" instead of silently showing a callee list shorter than the body's
+     * call sites, which reads as "nothing else happens here".
+     */
+    getUnresolvedReferencesFrom(fromNodeId) {
+        if (!this.stmts.getUnresolvedFromNode) {
+            // Insertion (extraction) order, stated: without ORDER BY the row order
+            // follows whichever index the planner picks — (from_node_id,
+            // reference_name) returns name order — and readers that stable-sort by
+            // position then break ties differently from build to build.
+            this.stmts.getUnresolvedFromNode = this.db.prepare('SELECT * FROM unresolved_refs WHERE from_node_id = ? ORDER BY id');
+        }
+        const rows = this.stmts.getUnresolvedFromNode.all(fromNodeId);
+        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,
+        }));
+    }
     /**
      * Find all edges where both source and target are in the given node set.
      * Useful for recovering inter-node connectivity after BFS.
@@ -1647,8 +2600,8 @@ 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, extraction_version, errors)
-        VALUES (@path, @contentHash, @language, @size, @modifiedAt, @indexedAt, @nodeCount, @extractionVersion, @errors)
+        INSERT INTO files (path, content_hash, language, size, modified_at, indexed_at, node_count, extraction_version, errors, generated)
+        VALUES (@path, @contentHash, @language, @size, @modifiedAt, @indexedAt, @nodeCount, @extractionVersion, @errors, @generated)
         ON CONFLICT(path) DO UPDATE SET
           content_hash = @contentHash,
           language = @language,
@@ -1657,7 +2610,8 @@ class QueryBuilder {
           indexed_at = @indexedAt,
           node_count = @nodeCount,
           extraction_version = @extractionVersion,
-          errors = @errors
+          errors = @errors,
+          generated = @generated
       `);
         }
         this.stmts.upsertFile.run({
@@ -1670,6 +2624,9 @@ class QueryBuilder {
             nodeCount: file.nodeCount,
             extractionVersion: file.extractionVersion,
             errors: file.errors ? JSON.stringify(file.errors) : null,
+            // The upsert always REWRITES the flag: a file that loses its banner in an
+            // edit must lose the flag on the next sync, not keep a stale 1.
+            generated: file.generated ? 1 : 0,
         });
     }
     /**
@@ -1711,6 +2668,173 @@ class QueryBuilder {
             .get(currentVersion);
         return row.ahead;
     }
+    /**
+     * Which of `filePaths` the index flagged as tool-generated (schema v9+).
+     *
+     * Bounded-lookup by design: every consumer already holds a short candidate
+     * list (a ranked file group, an FTS result page, a LIMIT-20 aggregate), so
+     * this stays a partial-index probe over a handful of paths — no whole-repo
+     * set to materialize, and no cache to invalidate, which means a ranking call
+     * can never serve a verdict the last sync already replaced.
+     *
+     * Returns ONLY the content/index signal; callers union it with
+     * {@link isGeneratedFile} so pre-v9 databases (column present, all zeros
+     * until a re-index) keep the path-only behavior rather than regressing.
+     */
+    getGeneratedPathsAmong(filePaths) {
+        const unique = [...new Set(filePaths)];
+        const found = new Set();
+        if (unique.length === 0)
+            return found;
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            const rows = this.db
+                .prepare(`SELECT path FROM files WHERE generated = 1 AND path IN (${placeholders})`)
+                .all(...chunk);
+            for (const row of rows)
+                found.add(row.path);
+        }
+        return found;
+    }
+    /**
+     * A reusable `(path) => boolean` over a bounded candidate list, unioning the
+     * indexed flag with the path convention. This is the shape every ranking
+     * comparator wants: one query up front, then O(1) per comparison.
+     */
+    generatedPredicateFor(filePaths) {
+        const flagged = this.getGeneratedPathsAmong(filePaths);
+        return (filePath) => flagged.has(filePath) || (0, generated_detection_1.isGeneratedFile)(filePath);
+    }
+    /**
+     * Which of `filePaths` are AMBIENT DECLARATION files — they declare nothing
+     * but types, and nothing in the index depends on them (CG-28). A hand-written
+     * ambient `.d.ts` of global shims, a vendored typings file, module
+     * augmentation: reachable only by name, structurally attached to nothing.
+     *
+     * Structural, not extension-based, so a hand-written `types.ts` and a `.d.ts`
+     * are judged by the same rule and a `.d.ts` that does declare a class or a
+     * const is (correctly) not caught. Four conditions, all required:
+     *
+     *   1. it declares at least one symbol — an empty or unparsed file is not a
+     *      declaration file, it is a file we know nothing about;
+     *   2. EVERY declared symbol is a type-level kind (interface / type alias /
+     *      enum / namespace). The narrowness is deliberate and measured: a rule
+     *      of "no callables" alone flags 1–18% of a repo, including Kotlin sealed
+     *      classes, Rust `mod.rs` re-exports and django's locale constant tables —
+     *      real source that must not be demoted. This rule flags 0–4%;
+     *   3. no symbol in it originates a `calls`/`instantiates` edge — the direct
+     *      evidence that nothing here has a body;
+     *   4. NOTHING ELSE IN THE INDEX points at it. This is the condition that
+     *      separates an ambient shim from a working type module, and it is why
+     *      the flag is narrow enough to be safe: `displacement-ts`'s pipeline
+     *      `types.ts` passes 1–3 identically but carries 13 inbound imports and
+     *      21 references, so the files that answer a query about the pipeline are
+     *      typed BY it — it is part of that answer's structure. An ambient
+     *      `declare global` shim has zero. Deliberately index-wide rather than
+     *      restricted to the candidate list: the file that imports it is usually
+     *      not itself a candidate.
+     *
+     * ### Interface MEMBERS are transparent to all four conditions
+     *
+     * A `method_signature` / `property_signature` inside an interface enters the
+     * graph as a `method` / `property` node (#1638). Read literally that would
+     * break every condition here at once: condition 2 sees non-type kinds and
+     * stops flagging, and — worse, because it is silent — condition 4 starts
+     * seeing inbound `calls` edges the moment a call site through the shim's API
+     * finally has a signature to land on. An ambient `.d.ts` would quietly lose
+     * its damping precisely BECAUSE the platform API it declares is widely used.
+     *
+     * So an interface-owned member is treated the way `parameter` already is: it
+     * neither qualifies, disqualifies, nor counts as inbound dependency. That is
+     * not a new judgement call, it is what keeps the rule measuring what it was
+     * measured on — before #1638 these nodes did not exist, so excluding them
+     * reproduces the 0–4% flag rate the thresholds above were tuned against. It
+     * is also the semantically right answer: a signature with no body is on the
+     * same side of the line as the interface that owns it, and a call edge
+     * landing on one is still not a file that can answer a flow question.
+     *
+     * The interface ITSELF is untouched: the `references` edges an importing
+     * module aims at `UploadStorage` still disqualify the file under (4), which
+     * is what keeps a depended-on `types.ts` out of the flag.
+     *
+     * Bounded-lookup like {@link getGeneratedPathsAmong}: callers hold a ranked
+     * candidate list, so this is a partial-index probe over a handful of paths.
+     */
+    getAmbientDeclarationPathsAmong(filePaths) {
+        const unique = [...new Set(filePaths)];
+        const found = new Set();
+        if (unique.length === 0)
+            return found;
+        for (let i = 0; i < unique.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+            const chunk = unique.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+            const placeholders = chunk.map(() => '?').join(',');
+            // `file`/`import`/`export`/`parameter` are structural bookkeeping, not
+            // things the file declares, so they neither qualify nor disqualify.
+            const rows = this.db
+                .prepare(`
+          SELECT n.file_path AS file_path,
+                 SUM(CASE WHEN n.kind NOT IN ('file','import','export','parameter')
+                           AND NOT ${IS_INTERFACE_MEMBER('n')}
+                          THEN 1 ELSE 0 END) AS declared,
+                 SUM(CASE WHEN n.kind IN ('interface','type_alias','enum','enum_member','namespace')
+                          THEN 1 ELSE 0 END) AS typeDeclared
+          FROM nodes n
+          WHERE n.file_path IN (${placeholders})
+          GROUP BY n.file_path
+        `)
+                .all(...chunk);
+            let candidates = rows
+                .filter((r) => r.declared > 0 && r.declared === r.typeDeclared)
+                .map((r) => r.file_path);
+            if (candidates.length === 0)
+                continue;
+            const disqualify = (sql) => {
+                if (candidates.length === 0)
+                    return;
+                const hit = new Set(this.db
+                    .prepare(sql.replace('$IN$', candidates.map(() => '?').join(',')))
+                    .all(...candidates).map((r) => r.file_path));
+                candidates = candidates.filter((p) => !hit.has(p));
+            };
+            // (3) originates behaviour — a signature has no body to originate from,
+            // so an edge attributed to one is not evidence about this file.
+            disqualify(`
+        SELECT DISTINCT n.file_path AS file_path
+        FROM edges e JOIN nodes n ON n.id = e.source
+        WHERE e.kind IN ('calls','instantiates') AND n.file_path IN ($IN$)
+          AND NOT ${IS_INTERFACE_MEMBER('n')}
+      `);
+            // (4) something outside the file depends on it — but a call that lands on
+            // an interface's own signature is a use of the API, not a dependency on
+            // this file's structure. The edges aimed at the interface still count.
+            disqualify(`
+        SELECT DISTINCT t.file_path AS file_path
+        FROM edges e JOIN nodes t ON t.id = e.target JOIN nodes s ON s.id = e.source
+        WHERE t.file_path IN ($IN$) AND s.file_path <> t.file_path
+          AND NOT ${IS_INTERFACE_MEMBER('t')}
+      `);
+            for (const path of candidates)
+                found.add(path);
+        }
+        return found;
+    }
+    /**
+     * A reusable `(path) => boolean` ambient-declaration test over a bounded
+     * candidate list — the shape a ranking comparator wants: one query up front,
+     * O(1) per comparison.
+     */
+    ambientDeclarationPredicateFor(filePaths) {
+        const flagged = this.getAmbientDeclarationPathsAmong(filePaths);
+        return (filePath) => flagged.has(filePath);
+    }
+    /** How many indexed files carry the generated flag. Surfaced by `status`. */
+    countGeneratedFiles() {
+        const row = this.db
+            .prepare('SELECT COUNT(*) AS n FROM files WHERE generated = 1')
+            .get();
+        return row?.n ?? 0;
+    }
     /**
      * Delete a file record and its nodes
      */
@@ -1753,6 +2877,40 @@ class QueryBuilder {
             .get();
         return row?.last ?? null;
     }
+    /**
+     * The index's revision marker: how far the last sync got, and how many files
+     * it left behind — one query, both numbers.
+     *
+     * This is the cheapest honest answer to "has the index moved since I last
+     * looked". `MAX(indexed_at)` alone is not enough: a sync that only DELETES
+     * files (a branch checkout that removed a directory) advances nothing, and
+     * the graph the viewer is showing has still changed underneath it. The row
+     * count catches exactly that case.
+     */
+    getIndexRevision() {
+        const row = this.db
+            .prepare('SELECT MAX(indexed_at) AS last, COUNT(*) AS files FROM files')
+            .get();
+        return { lastIndexedAt: row?.last ?? null, fileCount: row?.files ?? 0 };
+    }
+    /**
+     * Files re-indexed strictly after `since` (ms since epoch), newest first.
+     *
+     * `total` is the real count; `paths` is capped at `limit`. Used by the
+     * viewer's live channel to name what a sync just picked up. A file the same
+     * sync DELETED cannot appear here — it has no row left — which is why the
+     * caller compares {@link getIndexRevision} as well rather than treating an
+     * empty list as "nothing happened".
+     */
+    getFilesIndexedSince(since, limit) {
+        const count = this.db
+            .prepare('SELECT COUNT(*) AS n FROM files WHERE indexed_at > ?')
+            .get(since);
+        const rows = this.db
+            .prepare('SELECT path FROM files WHERE indexed_at > ? ORDER BY indexed_at DESC, path LIMIT ?')
+            .all(since, Math.max(0, limit));
+        return { paths: rows.map((r) => r.path), total: count?.n ?? rows.length };
+    }
     /**
      * Get files that need re-indexing (hash changed)
      */
@@ -1917,11 +3075,19 @@ class QueryBuilder {
      * (§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);
+    getUnresolvedReferencesBatchAfter(afterRowId, limit, prerequisites) {
+        // Resolution prerequisites must be committed before dependent calls,
+        // even when an interrupted sync queued their rows in a different order
+        // from a clean index (#1577). Each phase still seeks by row id in bounded
+        // memory; the default preserves the public reader's original enumeration.
+        const key = prerequisites === undefined ? 'getUnresolvedBatchAfter'
+            : prerequisites ? 'getUnresolvedPrerequisitesAfter' : 'getUnresolvedDependentsAfter';
+        if (!this.stmts[key]) {
+            const filter = prerequisites === undefined ? ''
+                : ` AND reference_kind ${prerequisites ? 'IN' : 'NOT IN'} ('imports', 'extends', 'implements')`;
+            this.stmts[key] = this.db.prepare(`SELECT * FROM unresolved_refs WHERE status = 'pending' AND id > ?${filter} ORDER BY id LIMIT ?`);
+        }
+        const rows = this.stmts[key].all(afterRowId, limit);
         return rows.map((row) => ({
             fromNodeId: row.from_node_id,
             referenceName: row.reference_name,
@@ -1991,7 +3157,13 @@ class QueryBuilder {
             const chunkRows = this.db
                 .prepare(`SELECT * FROM unresolved_refs WHERE status = 'pending' AND file_path IN (${placeholders})`)
                 .all(...chunk);
-            rows.push(...chunkRows);
+            // Append with a loop, never a spread: the INPUT chunk is bounded, but
+            // the RESULT rows per chunk are not — a dense recovery sync (e.g. the
+            // #1541 self-heal re-indexing hundreds of files) returns more rows than
+            // V8 allows as arguments, and `push(...chunkRows)` dies with "Maximum
+            // call stack size exceeded", aborting resolution mid-sync (#1558).
+            for (const row of chunkRows)
+                rows.push(row);
         }
         return rows.map((row) => ({
             fromNodeId: row.from_node_id,
@@ -2191,7 +3363,11 @@ class QueryBuilder {
             const chunkRows = this.db
                 .prepare(`SELECT * FROM unresolved_refs WHERE status = 'failed' AND name_tail IN (${placeholders})`)
                 .all(...chunk);
-            rows.push(...chunkRows);
+            // Loop, not spread — same V8 argument-limit hazard as
+            // getUnresolvedReferencesByFiles (#1558): a large definition delta can
+            // select an unbounded number of failed rows per chunk.
+            for (const row of chunkRows)
+                rows.push(row);
         }
         return rows.map((row) => ({
             fromNodeId: row.from_node_id,
@@ -2207,6 +3383,103 @@ class QueryBuilder {
             importedName: row.imported_name ?? undefined,
         }));
     }
+    /**
+     * Resolution edges whose TARGET symbol is named one of `names` — the edges a
+     * sync must re-resolve after `names` gained or lost a definition (CG-33).
+     *
+     * Resolution binds a reference to a node whose name matches the reference's
+     * tail, and it picks among ALL same-named definitions project-wide. So adding
+     * or removing one definition of `pct` changes the answer for every `pct(...)`
+     * reference in the repo — including references in files this sync never
+     * touches, whose edges nothing else revisits. Those edges' current target is,
+     * by that same rule, a node named `pct`, which is why the target's name is a
+     * sufficient (and index-backed, via idx_nodes_name) way to find them without
+     * a schema change or a scan of edge metadata.
+     *
+     * Returns the source file/language alongside each edge so the caller can
+     * resurrect it as its original reference. Excludes `provenance='heuristic'`
+     * (synthesized dispatch edges are not resolution output and carry no refName
+     * stamp to resurrect from — deleting one would be a permanent loss).
+     *
+     * 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;
+    }
+    /**
+     * Replace resolution edges with their original unresolved references as one
+     * transaction. If ref insertion fails, the edge deletion is rolled back.
+     */
+    replaceResolutionEdgesWithUnresolvedRefs(edgeIds, refs) {
+        return this.db.transaction(() => {
+            const changed = this.deleteEdgesByIds(edgeIds);
+            this.insertUnresolvedRefsBatch(refs);
+            return changed;
+        })();
+    }
     /**
      * 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.
@@ -2226,6 +3499,34 @@ class QueryBuilder {
         }
         return [...names];
     }
+    /**
+     * Distinct `file\0name` pairs defined by the given files — the shape sync's
+     * definition delta needs (CG-33).
+     *
+     * 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;
+    }
     // ===========================================================================
     // Statistics
     // ===========================================================================
@@ -2326,4 +3627,71 @@ class QueryBuilder {
     }
 }
 exports.QueryBuilder = QueryBuilder;
+function foldModuleRows(rows, options) {
+    // A module id is a path and may contain anything printable, so the key
+    // separator has to be something a path cannot hold.
+    const SEP = '\u0000';
+    const links = new Map();
+    const pairKinds = new Set(options.pairKinds);
+    const wantPairs = options.topPairsPerLink > 0 && pairKinds.size > 0;
+    const pairTotals = new Map();
+    for (const row of rows) {
+        const linkKey = `${row.source}${SEP}${row.target}${SEP}${row.kind}`;
+        const link = links.get(linkKey);
+        if (link) {
+            link.count += row.count;
+            link.declared += row.declared;
+            link.uncertain += row.uncertain;
+        }
+        else {
+            links.set(linkKey, {
+                source: row.source,
+                target: row.target,
+                kind: row.kind,
+                count: row.count,
+                declared: row.declared,
+                uncertain: row.uncertain,
+            });
+        }
+        // Only the confident half of a row can be named: an uncertain edge is a
+        // guess, and printing "a to b, 12" for twelve guesses is the map claiming
+        // something it does not know.
+        if (!wantPairs || row.count === 0 || !pairKinds.has(row.kind))
+            continue;
+        const pairKey = `${row.source}${SEP}${row.target}${SEP}${row.from}${SEP}${row.to}`;
+        const pair = pairTotals.get(pairKey);
+        if (pair) {
+            pair.count += row.count;
+            pair.declared += row.declared;
+        }
+        else {
+            pairTotals.set(pairKey, {
+                source: row.source,
+                target: row.target,
+                from: row.from,
+                to: row.to,
+                count: row.count,
+                declared: row.declared,
+            });
+        }
+    }
+    const byLink = new Map();
+    for (const pair of pairTotals.values()) {
+        const key = `${pair.source}${SEP}${pair.target}`;
+        let list = byLink.get(key);
+        if (!list)
+            byLink.set(key, (list = []));
+        list.push(pair);
+    }
+    const pairs = [];
+    for (const list of byLink.values()) {
+        list.sort((a, b) => b.declared - a.declared ||
+            b.count - a.count ||
+            a.from.localeCompare(b.from) ||
+            a.to.localeCompare(b.to));
+        for (const pair of list.slice(0, options.topPairsPerLink))
+            pairs.push(pair);
+    }
+    return { links: [...links.values()], pairs };
+}
 //# sourceMappingURL=queries.js.map