@quolu/lattice 0.70.0 → 0.71.0

package/sensor/dist/db/queries.d.ts

@@ -5,18 +5,38 @@
  */
 import { SqliteDatabase } from './sqlite-adapter';
 import { Node, Edge, FileRecord, UnresolvedReference, NodeKind, EdgeKind, Language, GraphStats, SearchOptions, SearchResult } from '../types';
+/**
+ * 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.
+ */
+export declare const DEPRIORITIZED_NAME_BONUS_SCALE = 0.75;
 /**
  * Query builder for the knowledge graph database
  */
 export declare class QueryBuilder {
     private db;
     private projectNameTokens;
+    private isDeprioritizedPath;
+    private _fts5Available;
     private nodeCache;
     private readonly maxCacheSize;
+    private dominantFileMemo;
     private stmts;
     private segmentedNames;
     private static readonly MAX_SEGMENTED_NAMES;
     private batchStmts;
+    private edgeKindStmts;
     private static readonly BATCH_SIZES;
     /**
      * Run `rows` through a multi-row `INSERT` built as `head + (tuple,)*n`,
@@ -37,11 +57,21 @@ export declare class QueryBuilder {
      * lazily on next use.
      */
     rebind(db: SqliteDatabase): void;
+    private edgeKindStmt;
     /** Set the normalized project-name tokens used to down-weight non-discriminative
      * query words in path scoring (#720). Called once when the project opens. */
     setProjectNameTokens(tokens: Set<string>): void;
     /** The normalized project-name tokens (#720); empty if none were derived. */
     getProjectNameTokens(): Set<string>;
+    /**
+     * 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: ((filePath: string) => boolean) | undefined): void;
+    /** The `deprioritize` predicate (#982), so other rankers apply the same lever. */
+    getDeprioritizedPathMatcher(): ((filePath: string) => boolean) | undefined;
     /**
      * Insert a new node
      */
@@ -157,10 +187,24 @@ export declare class QueryBuilder {
      * Clear the node cache
      */
     clearCache(): void;
+    /**
+     * 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: string): boolean;
+    /** The exported nodes of a file, in {@link getNodesByFile} order, decoding only those rows. */
+    getExportedNodesByFile(filePath: string): Node[];
+    /** The nodes of a file with one name, in {@link getNodesByFile} order, decoding only those rows. */
+    getNodesByFileAndName(filePath: string, name: string): Node[];
     /**
      * Get all nodes in a file
      */
     getNodesByFile(filePath: string): Node[];
+    /**
+     * Get all nodes in several files at once — one chunked `IN` query rather than
+     * one {@link getNodesByFile} per file (#1975).
+     */
+    getNodesByFiles(filePaths: readonly string[]): Node[];
     /**
      * Find the file that holds the densest concentration of the project's
      * internal call graph — the "core" file. Used by context-builder to
@@ -178,12 +222,29 @@ export declare 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(): {
         filePath: string;
         edgeCount: number;
         nextEdgeCount: number;
     } | null;
+    /**
+     * 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.
+     */
+    private getChangeStamp;
+    private computeDominantFile;
     /**
      * Find the file that holds the densest concentration of the project's
      * `route` nodes (framework-emitted: Express/Gin/Flask/Rails/Drupal/etc.).
@@ -219,6 +280,10 @@ export declare class QueryBuilder {
             handlerFile: string;
             handlerLine: number;
             handlerKind: string;
+            /** The route node itself: where the URL is REGISTERED, not where it is served. */
+            routeId: string;
+            routeFile: string;
+            routeLine: number;
         }>;
         topHandlerFile: string | null;
         topHandlerFileCount: number;
@@ -236,6 +301,14 @@ export declare class QueryBuilder {
      * memory O(1) in the node count rather than O(nodes) (#610).
      */
     iterateNodesByKind(kind: NodeKind): IterableIterator<Node>;
+    /**
+     * 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: NodeKind, languages: readonly string[]): IterableIterator<Node>;
     /**
      * Get all nodes in the database
      */
@@ -258,7 +331,22 @@ export declare class QueryBuilder {
      */
     getDistinctFileLanguages(): Set<string>;
     /**
-     * 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: string): Node[];
     /**
@@ -266,14 +354,27 @@ export declare class QueryBuilder {
      * skip idx_nodes_name under SQLite's default case-insensitive LIKE).
      */
     getNodesByNamePrefix(prefix: string, limit?: number): Node[];
+    /** File nodes whose basename starts with `prefix`, without a result cap. */
+    getFileNodesByNamePrefix(prefix: string): Node[];
     /**
      * Get nodes by exact qualified name match (uses idx_nodes_qualified_name index)
      */
     getNodesByQualifiedNameExact(qualifiedName: string): Node[];
     /**
-     * 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: string): Node[];
+    getNodesByLowerName(name: string): Node[];
     /**
      * Search nodes by name using FTS with fallback to LIKE for better matching
      *
@@ -299,6 +400,13 @@ export declare class QueryBuilder {
      * node count on any real codebase.
      */
     private searchNodesFuzzy;
+    /** Bounded miss diagnostics, independent of relevance filters and ranking. */
+    getExploreMissDiagnostics(query: string): {
+        matched: string[];
+        unmatched: string[];
+        candidates: string[];
+        limited: boolean;
+    };
     /**
      * FTS5 search with prefix matching
      */
@@ -329,6 +437,10 @@ export declare class QueryBuilder {
     findNodesByNameSubstring(substring: string, options?: SearchOptions & {
         excludePrefix?: boolean;
     }): SearchResult[];
+    /** Must run before file replacement/deletion cascades the endpoint edges. */
+    hasSynthesizedEdgesTouchingFile(filePath: string): boolean;
+    wasSynthesisInput(filePath: string): boolean;
+    replaceSynthesisInputs(files: string[]): void;
     /**
      * Insert a new edge
      */
@@ -342,13 +454,318 @@ export declare class QueryBuilder {
      */
     deleteEdgesBySource(sourceId: string): void;
     /**
-     * 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: string, kinds?: EdgeKind[], provenance?: string): Edge[];
     /**
-     * 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: string, kinds?: EdgeKind[]): Edge[];
+    /**
+     * 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: readonly string[], kinds?: EdgeKind[]): Edge[];
+    /**
+     * 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: readonly string[]): Map<string, number>;
+    /**
+     * 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: readonly string[], kinds?: EdgeKind[]): Edge[];
+    /**
+     * 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: readonly string[]): Map<string, number>;
+    /**
+     * 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: readonly string[], limit: number): Array<{
+        node: Node;
+        generated: boolean;
+    }>;
+    /**
+     * 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: Iterable<string>): Set<string>;
+    /**
+     * 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: Iterable<string>): Set<string>;
+    /**
+     * 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: Iterable<string>): Set<string>;
+    /**
+     * 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: Iterable<string>): Set<string>;
+    /**
+     * 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: number): Array<{
+        nodeId: string;
+        dependents: number;
+    }>;
+    /**
+     * 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: number): Array<{
+        nodeId: string;
+        filePath: string;
+        calls: number;
+        reaches: number;
+        score: number;
+    }>;
+    /**
+     * 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: string[]): Array<{
+        filePath: string;
+        dependents: number;
+    }>;
+    /**
+     * 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: string[]): Array<{
+        filePath: string;
+        reaches: number;
+        refs: number;
+    }>;
+    /**
+     * 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: string[]): Node[];
+    /**
+     * 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: ReadonlyArray<{
+        filePath: string;
+        module: string;
+    }>, options: {
+        kinds: readonly EdgeKind[];
+        minConfidence: number;
+        topPairsPerLink: number;
+        pairKinds: readonly EdgeKind[];
+    }): {
+        links: Array<{
+            source: string;
+            target: string;
+            kind: EdgeKind;
+            count: number;
+            declared: number;
+            uncertain: number;
+        }>;
+        pairs: Array<{
+            source: string;
+            target: string;
+            from: string;
+            to: string;
+            count: number;
+            declared: number;
+        }>;
+    };
+    /**
+     * 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: number): Array<{
+        source: string;
+        target: string;
+    }>;
+    /**
+     * 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: string, limit?: number): UnresolvedReference[];
+    /**
+     * 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: string): UnresolvedReference[];
     /**
      * Find all edges where both source and target are in the given node set.
      * Useful for recovering inter-node connectivity after BFS.
@@ -422,6 +839,90 @@ export declare class QueryBuilder {
      * wonder why the index never converges.
      */
     getExtractionAheadFileCount(currentVersion: number): number;
+    /**
+     * 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: Iterable<string>): Set<string>;
+    /**
+     * 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: Iterable<string>): (filePath: string) => boolean;
+    /**
+     * 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: Iterable<string>): Set<string>;
+    /**
+     * 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: Iterable<string>): (filePath: string) => boolean;
+    /** How many indexed files carry the generated flag. Surfaced by `status`. */
+    countGeneratedFiles(): number;
     /**
      * Delete a file record and its nodes
      */
@@ -439,6 +940,33 @@ export declare class QueryBuilder {
      * null when nothing is indexed yet. One indexed aggregate, no per-row scan. (#329)
      */
     getLastIndexedAt(): number | 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(): {
+        lastIndexedAt: number | null;
+        fileCount: number;
+    };
+    /**
+     * 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: number, limit: number): {
+        paths: string[];
+        total: number;
+    };
     /**
      * Get files that need re-indexing (hash changed)
      */
@@ -486,7 +1014,7 @@ export declare 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: number, limit: number): UnresolvedReference[];
+    getUnresolvedReferencesBatchAfter(afterRowId: number, limit: number, prerequisites?: boolean): UnresolvedReference[];
     /**
      * Get all tracked file paths (lightweight — no full FileRecord objects)
      */
@@ -579,11 +1107,60 @@ export declare class QueryBuilder {
      * arbitrary subset would be both wasted work and incoherent coverage.
      */
     getRetryableFailedReferences(names: string[], perNameCeiling?: number): UnresolvedReference[];
+    /**
+     * 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: string[], perNameCeiling?: number): Array<Edge & {
+        edgeId: number;
+        sourceFilePath: string;
+        sourceLanguage: Language;
+    }>;
+    /** Delete edges by primary key — the rebind pass's half of a re-resolution. */
+    deleteEdgesByIds(edgeIds: number[]): number;
+    /**
+     * Replace resolution edges with their original unresolved references as one
+     * transaction. If ref insertion fails, the edge deletion is rolled back.
+     */
+    replaceResolutionEdgesWithUnresolvedRefs(edgeIds: number[], refs: UnresolvedReference[]): number;
     /**
      * Distinct node names present in the given files — the symbol names a sync
      * pass uses to look up retryable failed refs after those files changed.
      */
     getNodeNamesByFiles(filePaths: string[]): string[];
+    /**
+     * 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: string[]): Set<string>;
     /**
      * Lightweight (nodes, edges) count snapshot. Used around an index/sync
      * run to compute true additions across extraction + resolution +