seer-mcp 0.1.0

package/dist/db/store.d.ts

@@ -0,0 +1,1011 @@
+import { DatabaseSync } from 'node:sqlite';
+import type { SymbolDef, SymbolRow, CallerRow, CalleeRow, StatsRow, RouteRow, ExternalDepRow, ConfigKeyRow, FileChurnRow, SymbolHistoryRow } from '../types.js';
+export declare function isRankableKind(kind: string): boolean;
+export interface EdgeResolutionStats {
+    sameFile: number;
+    imported: number;
+    global: number;
+    total: number;
+}
+/**
+ * What kind of code a file is. Used to keep project-owned code from being
+ * drowned out by vendored or generated boilerplate in ranking and search.
+ */
+export type FileRole = 'project' | 'vendor' | 'generated' | 'test';
+export interface FileClassification {
+    role: FileRole;
+    isVendor: 0 | 1;
+    isGenerated: 0 | 1;
+}
+export interface SymbolSearchOptions {
+    limit?: number;
+    includeVendor?: boolean;
+    includeGenerated?: boolean;
+    /**
+     * When false (default for agent-facing search/ranking), file-role=test
+     * symbols are filtered out. seer_behavior bypasses this because the test
+     * relationship IS its content; everything else (top symbols, search, deps,
+     * complexity) should default to non-test code so agents don't get drowned
+     * in test names. Indexer-wide test indexing stays on so seer_behavior keeps
+     * working — this filter is purely query-side.
+     */
+    includeTests?: boolean;
+    /**
+     * When false (default), rows where symbol_role='declaration' (forward
+     * declarations, C++ class-body method declarations whose bodies live
+     * out-of-line) are hidden. Pass true to include them — useful for
+     * "show me every place this method is announced" workflows.
+     */
+    includeDeclarations?: boolean;
+    /**
+     * When false (default), symbol_role='type_ref' rows stay hidden. Currently
+     * Seer's extractors never emit type-ref rows, so the flag is a forward-
+     * looking opt-in for future indexing modes that materialize them.
+     */
+    includeTypeRefs?: boolean;
+}
+export interface StoreOptions {
+    readonly?: boolean;
+    busyTimeoutMs?: number;
+}
+export interface SchemaInfo {
+    dbVersion: number;
+    buildVersion: number;
+    current: boolean;
+}
+/**
+ * Split an identifier into searchable tokens. Used at FTS-insert time so a
+ * query for "auth" finds `AuthService`, `auth_service`, `authService`, and
+ * `AuthServiceImpl` alike.
+ *
+ *  - splits on _ and -
+ *  - splits camelCase boundaries (`AuthService` → "Auth Service Auth_Service")
+ *  - splits consecutive caps like XMLParser → "XML Parser"
+ *  - always includes the original token so prefix matches still work
+ */
+export declare function splitIdentifierTokens(s: string): string;
+export declare class Store {
+    private db;
+    private readonly readonly;
+    private cachedSchemaInfo;
+    private hasRoleColumns;
+    private hasComplexityColumns;
+    private hasV4Tables;
+    /**
+     * True when the v5 `symbols.symbol_role` column exists. Read-only opens
+     * against a pre-v5 DB transparently skip declaration/type_ref filtering;
+     * writer opens always have it since runMigrations() adds the column.
+     */
+    private hasSymbolRoleColumn;
+    /**
+     * True when the v6 module tables (modules / module_members / module_edges)
+     * exist. Read-only opens against a pre-v6 DB skip module queries gracefully
+     * (they return empty arrays); writer opens always have it.
+     */
+    private hasModuleTables;
+    /**
+     * True when the v7 provenance/shape_hash columns + scip_imports table exist.
+     * Read-only opens against a pre-v7 DB return empty arrays for SCIP / dup
+     * queries and skip the provenance column on selects.
+     */
+    private hasV7Columns;
+    /**
+     * True when v10 external_bundles / boundaries / symbol_history_continuity
+     * tables exist. Read-only opens against a pre-v10 DB return empty arrays.
+     */
+    private hasV10Tables;
+    private stmtUpsertFile;
+    private stmtInsertSymbol;
+    private stmtInsertEdge;
+    private stmtInsertFileImport;
+    private stmtInsertRoute;
+    private stmtInsertConfigKey;
+    private stmtInsertExternalDep;
+    private stmtInsertServiceCall;
+    private stmtInsertServiceLink;
+    private stmtInsertSymbolsFts;
+    private stmtInsertFilesFts;
+    private stmtDeleteSymbolsFtsForFile;
+    private stmtDeleteFilesFtsForFile;
+    constructor(dbPath: string, options?: StoreOptions);
+    private checkHasV10Tables;
+    private checkHasModuleTables;
+    private checkHasRoleColumns;
+    private checkHasV4Tables;
+    static openReadOnly(dbPath: string, busyTimeoutMs?: number): Store;
+    isReadOnly(): boolean;
+    private assertWritable;
+    schemaInfo(): SchemaInfo;
+    /**
+     * v8 Track-G migration guard. When an existing v7 DB is opened by v8 code,
+     * service_calls/service_links tables are created empty. A normal cached
+     * re-index would skip every unchanged file, so service_calls would remain
+     * empty forever. Until an index run marks this backfill version complete,
+     * the indexer must force one full parse pass.
+     */
+    needsServiceCallBackfill(): boolean;
+    markServiceCallsBackfilled(): void;
+    private readSchemaInfo;
+    private runMigrations;
+    /**
+     * Populate symbols.symbol_key for every existing row. Mirrors
+     * makeSymbolKey() — `kind:qualified_name` (or `kind:name` if qualified is
+     * NULL). symbol_history is keyed on these so without the backfill,
+     * listSymbolsForHistoryIndex() returns zero candidates after a v3→v4
+     * upgrade.
+     */
+    private backfillSymbolKeysFromExistingRows;
+    /**
+     * Rebuild symbols_fts / files_fts from the current symbols / files rows if
+     * either FTS table is empty while its source table has rows. This is the
+     * only safe trigger condition — Seer never deliberately leaves FTS empty
+     * while symbols are populated, so emptiness is a reliable "stale FTS"
+     * signal (post-migration or post-manual-patch).
+     */
+    private rebuildFtsIfStale;
+    private hasColumn;
+    private addColumnIfMissing;
+    private prepare;
+    pruneFilesNotIn(keepIds: Set<number>): number;
+    upsertFile(path: string, relPath: string, language: string, hash: string, lines: number, classification?: FileClassification): number;
+    upsertFileWithCache(path: string, relPath: string, language: string, hash: string, lines: number, classification?: FileClassification): {
+        fileId: number;
+        unchanged: boolean;
+    };
+    insertSymbol(fileId: number, def: SymbolDef): number;
+    insertEdge(fromSymbolId: number, toName: string, kind: string, line: number): void;
+    insertFileImport(fromFileId: number, importName: string): void;
+    insertRoute(fileId: number, method: string, routePath: string, framework: string, handlerName: string | null, line: number, options?: {
+        protocol?: string;
+        operation?: string | null;
+        topic?: string | null;
+        queue?: string | null;
+        exchange?: string | null;
+        service?: string | null;
+        broker?: string | null;
+        metadataJson?: string | null;
+    }): void;
+    insertConfigKey(key: string, source: string, fileId: number, symbolId: number | null, line: number): void;
+    /**
+     * v8 Track G — return a closure that inserts service_link rows. Used by
+     * the resolver in `resolveServiceLinks(store)` so it can stream inserts
+     * inside one prepared statement rather than re-resolving the statement
+     * per row.
+     */
+    makeServiceLinkInserter(): (args: {
+        callId: number;
+        routeId: number | null;
+        callerSymbolId: number | null;
+        handlerSymbolId: number | null;
+        protocol: string;
+        matchKind: string;
+        confidence: number;
+        evidenceJson: string;
+    }) => void;
+    /**
+     * v8 Track G — insert a service-call row (outbound HTTP/etc. client call).
+     * The post-index resolver derives service_links from these and from routes.
+     * Returns the new row id so callers can attach evidence in the same batch.
+     */
+    insertServiceCall(args: {
+        fileId: number;
+        symbolId: number | null;
+        protocol: string;
+        method: string | null;
+        rawTarget: string;
+        normalizedPath: string | null;
+        hostHint: string | null;
+        envKey: string | null;
+        framework: string;
+        line: number;
+        confidence: number;
+        operation?: string | null;
+        topic?: string | null;
+        queue?: string | null;
+        exchange?: string | null;
+        service?: string | null;
+        broker?: string | null;
+        metadataJson?: string | null;
+    }): number;
+    insertExternalDep(ecosystem: string, name: string, versionRange: string | null, manifestPath: string, isDev: 0 | 1): void;
+    clearExternalDeps(): void;
+    resolveImports(): number;
+    resolveEdges(): EdgeResolutionStats;
+    /**
+     * After symbol IDs are known, link routes.handler_id by name. Routes that
+     * named a handler not defined in the same file stay with handler_id NULL.
+     * Matching is by `handler_name = symbols.name` AND `file_id = routes.file_id`
+     * — handlers nearly always live in the same file as the route registration.
+     */
+    resolveRouteHandlers(): number;
+    /**
+     * Backfill config_keys.symbol_id by line span. The extractor doesn't always
+     * know the enclosing symbol id (extraction precedes symbol insertion), so we
+     * resolve it via "the smallest function/method containing this line."
+     */
+    resolveConfigKeySymbols(): number;
+    /**
+     * Promote calls from a test-file symbol to a non-test target into 'tests'
+     * edges (in addition to keeping the original 'call' edge). The original
+     * call edge is left in place so caller/callee queries don't double-count;
+     * test edges live in their own kind so `seer_behavior` can pull them
+     * directly without scanning the full edge table.
+     *
+     * The synthesized edge copies the SOURCE 'call' edge's `to_id` verbatim —
+     * the call-edge resolution pass already did the same-file / imported /
+     * global fallback work to pick the correct target. Re-resolving by name
+     * via `WHERE name = edges.to_name LIMIT 1` (the old behavior) was buggy
+     * when two symbols shared the same short name (`Alpha.run` / `Beta.run`):
+     * `LIMIT 1` would attribute every test edge to whichever id sorted first,
+     * so `seer_behavior(Beta.run)` returned tests that actually exercised
+     * `Alpha.run`. Preserving the source `to_id` matches what the original
+     * resolver already chose.
+     *
+     * Returns the number of new test edges inserted.
+     */
+    synthesizeTestEdges(): number;
+    findCallers(symbolName: string, limit?: number): CallerRow[];
+    countCallers(symbolName: string): number;
+    /**
+     * Callers of a specific symbol id — never collapses short-name siblings.
+     * Track E + any tool that already has a resolved symbol id should use
+     * this instead of `findCallers(name)`. Edges whose `to_id` is NULL
+     * (unresolved) are intentionally skipped: with no resolved id we can't
+     * tell whether they target THIS specific symbol vs. a same-short-name
+     * sibling, and Track E callers want id-specificity.
+     */
+    findCallersById(symbolId: number, limit?: number): CallerRow[];
+    /** Count of callers for a specific symbol id (id-scoped). */
+    countCallersById(symbolId: number): number;
+    /**
+     * Callees emitted by a specific caller symbol id — never collapses
+     * short-name siblings the way `findCallees(name)` does. Returns one row
+     * per call edge.
+     */
+    findCalleesById(symbolId: number): CalleeRow[];
+    findCallees(symbolName: string): CalleeRow[];
+    /**
+     * Build the predicate suffix shared by findSymbols / getDefinition /
+     * getTopSymbols / countSymbols. Returns the `AND …` string that augments a
+     * WHERE clause; never starts the WHERE itself so callers control the rest.
+     */
+    private filterClauseFromOptions;
+    findSymbols(name: string, options?: SymbolSearchOptions): SymbolRow[];
+    /**
+     * FTS5 search across symbol name / qualified_name / signature / split form.
+     * Falls back to `findSymbols` (LIKE) when FTS5 isn't available or returns
+     * nothing. Returns BM25-ranked results.
+     */
+    searchSymbolsFts(query: string, options?: SymbolSearchOptions): SymbolRow[];
+    /**
+     * FTS5 search over file paths. Returns matching files ranked by BM25.
+     */
+    searchFilesFts(query: string, limit?: number, options?: {
+        includeTests?: boolean;
+        includeVendor?: boolean;
+        includeGenerated?: boolean;
+    }): Array<{
+        id: number;
+        path: string;
+        relPath: string;
+        language: string;
+        role: string;
+    }>;
+    listSymbolsInFile(filePath: string, limit?: number): SymbolRow[];
+    getTopSymbols(limit?: number, options?: SymbolSearchOptions): SymbolRow[];
+    getDefinition(name: string, options?: {
+        filePath?: string;
+    } & SymbolSearchOptions): SymbolRow[];
+    getSymbolById(id: number): SymbolRow | null;
+    countSymbols(name: string, options?: SymbolSearchOptions): number;
+    listFiles(): Array<{
+        id: number;
+        path: string;
+        relPath: string;
+        language: string;
+        hash: string;
+        indexedAt: number;
+        role: string;
+        isVendor: number;
+        isGenerated: number;
+    }>;
+    getRoleCounts(): {
+        project: number;
+        vendor: number;
+        generated: number;
+        test: number;
+    };
+    listRoutes(options?: {
+        method?: string;
+        pathSubstr?: string;
+        framework?: string;
+        /** v9 Track-H — filter by protocol ('http' / 'trpc' / 'graphql' / 'grpc' / 'kafka' / ...). */
+        protocol?: string;
+        operation?: string;
+        topic?: string;
+        queue?: string;
+        service?: string;
+        limit?: number;
+    }): RouteRow[];
+    countRoutes(): number;
+    /** Total count of service_calls rows. */
+    countServiceCalls(): number;
+    /** Total count of service_links rows. */
+    countServiceLinks(): number;
+    /** List service_calls with the AST-attributed caller joined in. */
+    listServiceCalls(options?: {
+        protocol?: string;
+        method?: string;
+        pathSubstr?: string;
+        framework?: string;
+        callerSymbolId?: number;
+        minConfidence?: number;
+        /** v9 Track-H — filter by tRPC procedure / GraphQL operation / gRPC method. */
+        operation?: string;
+        /** v9 Track-H — filter by Kafka / pubsub topic. */
+        topic?: string;
+        /** v9 Track-H — filter by SQS / RabbitMQ queue. */
+        queue?: string;
+        /** v9 Track-H — filter by gRPC service / k8s service host. */
+        service?: string;
+        limit?: number;
+        offset?: number;
+    }): import('../types.js').ServiceCallRow[];
+    /** List service_links with caller + handler + route joined in. */
+    listServiceLinks(options?: {
+        protocol?: string;
+        method?: string;
+        pathSubstr?: string;
+        callerSymbolId?: number;
+        handlerSymbolId?: number;
+        matchKind?: string;
+        minConfidence?: number;
+        limit?: number;
+        offset?: number;
+    }): import('../types.js').ServiceLinkRow[];
+    /** id-scoped helper: every service_link whose caller is symbolId. */
+    serviceLinksForCaller(symbolId: number, options?: {
+        limit?: number;
+    }): import('../types.js').ServiceLinkRow[];
+    /** id-scoped helper: every service_link whose handler is symbolId. */
+    serviceLinksForHandler(symbolId: number, options?: {
+        limit?: number;
+    }): import('../types.js').ServiceLinkRow[];
+    /**
+     * Bounded BFS over service_links from caller to handler. Treats each
+     * service_link as a directed edge `caller_symbol_id → handler_symbol_id`.
+     * Returns the shortest path as an array of symbol ids, or [] if unreachable
+     * within maxDepth. Combines with the normal call-graph trace done by
+     * `tracePath`; this one is service-link only.
+     */
+    traceServicePath(fromSymbolId: number, toSymbolId: number, maxDepth?: number): number[];
+    /**
+     * v9 Track-H — bounded service-link traversal from a single symbol.
+     *
+     * Walks the directed service-link graph starting at `fromSymbolId`. Each
+     * step follows `caller_symbol_id → handler_symbol_id` edges, recording the
+     * protocol / matchKind / hop chain for every reachable handler.
+     *
+     * Bounds (all configurable; defaults are conservative):
+     *   - maxDepth     limit hops away from the source (default 4)
+     *   - maxNodes     stop after expanding this many handlers (default 200)
+     *   - maxFanout    stop expanding a node after this many outgoing service
+     *                  links (default 20)
+     *
+     * Returns one record per reached handler with the protocols and match-kinds
+     * encountered along the path; `cutoff` flags the limit that fired (if any).
+     */
+    traceServiceDependencies(fromSymbolId: number, options?: {
+        maxDepth?: number;
+        maxNodes?: number;
+        maxFanout?: number;
+    }): {
+        reached: Array<{
+            symbolId: number;
+            depth: number;
+            protocols: string[];
+            matchKinds: string[];
+            hops: number[];
+        }>;
+        cutoff: 'maxNodes' | 'maxDepth' | 'maxFanout' | null;
+        fromExpanded: number;
+    };
+    /**
+     * v9 Track-H — bounded service-link traversal at module granularity.
+     *
+     * Returns the set of modules reachable from `fromModuleId` by following
+     * cross-module service links (one or more service_link edges whose caller
+     * and handler live in different modules). For each reached module the
+     * result includes the minimum hop depth and which protocols carry traffic
+     * into it.
+     *
+     * Useful for "which modules depend on `billing` through HTTP/Kafka/etc?".
+     */
+    traceModuleServiceDependencies(fromModuleId: number, options?: {
+        maxDepth?: number;
+        maxNodes?: number;
+    }): {
+        reached: Array<{
+            moduleId: number;
+            depth: number;
+            protocols: string[];
+            viaLinks: number;
+        }>;
+        cutoff: 'maxNodes' | 'maxDepth' | null;
+    };
+    /** True iff the v10 external/boundary/continuity tables exist on disk. */
+    hasV10(): boolean;
+    /** Replace the boundaries / boundary_members / boundary_edges tables.
+     *  Atomic — wrapped in a single transaction. */
+    replaceBoundaries(boundaries: Array<{
+        label: string;
+        kind: string;
+        rootRelPath: string;
+        manifestPath: string | null;
+        ecosystem: string | null;
+        fileIds: number[];
+    }>, edges: Array<{
+        fromIndex: number;
+        toIndex: number;
+        kind: string;
+        weight: number;
+    }>): void;
+    /** True iff boundaries were populated this build. */
+    hasBoundariesData(): boolean;
+    countBoundaries(): number;
+    listBoundaries(limit?: number): Array<{
+        id: number;
+        label: string;
+        kind: string;
+        rootRelPath: string;
+        manifestPath: string | null;
+        ecosystem: string | null;
+        sizeFiles: number;
+    }>;
+    /** Boundary that owns a file id (or null). */
+    boundaryForFile(fileId: number): {
+        id: number;
+        label: string;
+        kind: string;
+        rootRelPath: string;
+    } | null;
+    /** Cross-boundary dependency edges from a boundary (outgoing by default). */
+    boundaryDependencies(boundaryId: number, options?: {
+        direction?: 'in' | 'out';
+        limit?: number;
+    }): Array<{
+        boundaryId: number;
+        label: string;
+        kind: string;
+        weight: number;
+    }>;
+    /** For a given symbol id, return the boundaries of each of its callees. */
+    calleeBoundariesOf(symbolId: number): Array<{
+        calleeId: number;
+        boundaryId: number;
+    }>;
+    /**
+     * Return every files.id that's actually a phantom file backing an external
+     * bundle layer. The indexer's prune pass preserves these so a local
+     * re-index never drops external-imported rows.
+     */
+    listExternalPhantomFileIds(): number[];
+    /** Insert (or replace) an external_bundles row for a given bundle path. */
+    upsertExternalBundle(args: {
+        bundlePath: string;
+        externalProject: string | null;
+        externalVersion: string | null;
+        externalHash: string | null;
+        schemaVersion: number;
+        routesImported: number;
+        serviceCallsImported: number;
+        serviceLinksImported: number;
+    }): number;
+    /**
+     * Look up an existing external_bundles row by its bundle path. Returns the
+     * id and the imported_at/external_hash for the existing layer when present.
+     */
+    findExternalBundleByPath(bundlePath: string): {
+        id: number;
+        bundlePath: string;
+        externalProject: string | null;
+        externalVersion: string | null;
+        externalHash: string | null;
+    } | null;
+    /** List every external_bundles row (newest first). */
+    listExternalBundles(): Array<{
+        id: number;
+        sourceKind: string;
+        bundlePath: string;
+        externalProject: string | null;
+        externalVersion: string | null;
+        externalHash: string | null;
+        schemaVersion: number;
+        importedAt: number;
+        routesImported: number;
+        serviceCallsImported: number;
+        serviceLinksImported: number;
+    }>;
+    /**
+     * Delete every row associated with a given external_bundles.id — its
+     * routes/service_calls/service_links rows and the bundle row itself. Used
+     * during re-import so a fresh import is fully replacing the previous
+     * snapshot of that bundle.
+     */
+    clearExternalBundle(bundleId: number): {
+        routes: number;
+        serviceCalls: number;
+        serviceLinks: number;
+    };
+    /**
+     * Insert a route from an external bundle. file_id is intentionally NULL —
+     * external routes do not belong to any local file. The Store schema does
+     * not allow NULL on routes.file_id by default; v10 keeps file_id NOT NULL,
+     * so we have to ensure an external "phantom" file row exists per bundle to
+     * own the routes. The route stays linked to the external_bundle_id so we
+     * can wipe them as a layer.
+     */
+    insertExternalRoute(args: {
+        bundleId: number;
+        externalFileId: number;
+        method: string;
+        path: string;
+        framework: string;
+        handlerName: string | null;
+        line: number;
+        protocol?: string;
+        operation?: string | null;
+        topic?: string | null;
+        queue?: string | null;
+        exchange?: string | null;
+        service?: string | null;
+        broker?: string | null;
+        metadataJson?: string | null;
+    }): number;
+    /**
+     * Create (or reuse) an "external" phantom file row that owns external
+     * bundle rows. Each external_bundles.id gets its own external-phantom file
+     * so deleting a layer doesn't disturb sibling layers. The phantom file
+     * carries role='vendor' so it stays out of project-first defaults.
+     */
+    ensureExternalFile(bundleId: number, externalProject: string): number;
+    /** Count of routes that came from an external bundle. */
+    countExternalRoutes(): number;
+    /**
+     * List routes filtered to external bundles only. Useful for verifying that
+     * an external import landed and for the seer_external_bundles MCP tool.
+     */
+    listExternalRoutes(options?: {
+        bundleId?: number;
+        method?: string;
+        pathSubstr?: string;
+        protocol?: string;
+        limit?: number;
+    }): Array<{
+        id: number;
+        method: string;
+        path: string;
+        framework: string;
+        handlerName: string | null;
+        line: number;
+        protocol: string | null;
+        operation: string | null;
+        topic: string | null;
+        queue: string | null;
+        service: string | null;
+        externalBundleId: number;
+        externalProject: string | null;
+    }>;
+    listExternalDeps(options?: {
+        ecosystem?: string;
+        nameSubstr?: string;
+        limit?: number;
+    }): ExternalDepRow[];
+    countExternalDeps(): number;
+    listConfigKeys(options?: {
+        key?: string;
+        source?: string;
+        limit?: number;
+    }): ConfigKeyRow[];
+    countConfigKeys(): number;
+    upsertFileChurn(fileId: number, commitCount: number, lastCommitSha: string | null, lastCommitAt: number | null, topAuthor: string | null, secondAuthor: string | null): void;
+    getFileChurn(filePath: string): FileChurnRow | null;
+    topChurnedFiles(limit?: number): FileChurnRow[];
+    insertSymbolHistory(symbolId: number, symbolKey: string, commitSha: string, authorName: string | null, authorEmail: string | null, committedAt: number, message: string | null, linesAdded: number, linesRemoved: number, prNumber: number | null, prUrl: string | null, matchStrategy: string, confidence: number): void;
+    getSymbolHistory(symbolId: number, options?: {
+        limit?: number;
+        since?: number;
+    }): SymbolHistoryRow[];
+    /** Total history count for a symbol — for "showing N of M commits" headers. */
+    countSymbolHistory(symbolId: number): number;
+    getGitIndexState(): {
+        repoRoot: string;
+        lastHeadSha: string | null;
+        lastProcessedAt: number;
+        remoteUrl: string | null;
+        algorithmVersion: number;
+        lastHistoryHeadSha: string | null;
+        lastHistoryAt: number | null;
+    } | null;
+    /**
+     * Generic "the indexer has seen this HEAD" stamp — used by churn and any
+     * other read-only git pass. Does NOT touch the history-specific marker.
+     * symbol-history has its own setHistoryHeadSha() so the two passes can't
+     * mask each other.
+     */
+    setGitIndexState(repoRoot: string, lastHeadSha: string | null, remoteUrl: string | null, algorithmVersion?: number): void;
+    /**
+     * Stamp the HEAD that symbol-history was last built against. Independent of
+     * setGitIndexState() so running file-level churn never makes a subsequent
+     * buildSymbolHistory() skip.
+     */
+    setHistoryHeadSha(repoRoot: string, lastHistoryHeadSha: string | null, remoteUrl: string | null): void;
+    /** All symbols matching a symbol_key — used by `seer_history` to find the
+     *  current id for a key that came from the indexed graph. */
+    findSymbolsByKey(symbolKey: string): SymbolRow[];
+    /** Iterate over (id, file_id, line_start, line_end, symbol_key) — used by
+     *  the symbol-history indexer to map historical line ranges to current ids. */
+    listSymbolsForHistoryIndex(): Array<{
+        id: number;
+        fileId: number;
+        filePath: string;
+        relPath: string;
+        lineStart: number;
+        lineEnd: number;
+        symbolKey: string;
+    }>;
+    getAllEdges(): Array<{
+        from: number;
+        to: number;
+    }>;
+    getAllSymbolIds(): number[];
+    updatePageRanks(ranks: Map<number, number>): void;
+    /**
+     * Bounded breadth-first search over the call graph. Returns one shortest
+     * path from `fromId` to `toId` (by edge count), or null if none found.
+     * The search expands at most `maxDepth` hops and at most `maxNodes` nodes
+     * visited overall — without those caps a cycle in the graph would explode.
+     */
+    tracePath(fromId: number, toId: number, maxDepth?: number, maxNodes?: number): Array<{
+        id: number;
+        name: string;
+        qualifiedName: string | null;
+        kind: string;
+        filePath: string;
+    }> | null;
+    /** Reverse BFS from a symbol — for "everything that transitively calls X". */
+    reverseReachable(toId: number, maxDepth?: number, maxNodes?: number): number[];
+    /**
+     * Bounded reverse-reachable callers WITH depth, for risk/context callers.
+     * Same termination semantics as reverseReachable() but returns the depth
+     * at which each id was first discovered (1-indexed; direct callers = 1).
+     */
+    reverseReachableWithDepth(toId: number, maxDepth?: number, maxNodes?: number): Array<{
+        id: number;
+        depth: number;
+    }>;
+    /**
+     * Bounded forward-reachable callees with depth — for callee blast-radius
+     * questions and behavioral indirect-coverage. Mirror of
+     * reverseReachableWithDepth().
+     */
+    forwardReachableWithDepth(fromId: number, maxDepth?: number, maxNodes?: number): Array<{
+        id: number;
+        depth: number;
+    }>;
+    /**
+     * Bounded BFS over the file-import graph. Used by
+     * seer_trace_file_dependencies — returns each reachable file with the BFS
+     * depth at which we first saw it.
+     */
+    fileImportClosure(fileId: number, maxDepth?: number, maxNodes?: number): Array<{
+        id: number;
+        depth: number;
+        relPath: string;
+        language: string;
+    }>;
+    /**
+     * All cross-file call edges as (fromFile, toFile, weight) triples.
+     * Used by the Louvain clusterer; only resolved 'call' edges count.
+     */
+    fileCallEdgeWeights(): Array<{
+        from: number;
+        to: number;
+        weight: number;
+    }>;
+    /** Resolved cross-file import edges as (fromFile, toFile, weight). */
+    fileImportEdgeWeights(): Array<{
+        from: number;
+        to: number;
+        weight: number;
+    }>;
+    /** Synthesized test → production edges, file-aggregated. */
+    fileTestEdgeWeights(): Array<{
+        from: number;
+        to: number;
+        weight: number;
+    }>;
+    /**
+     * v8 Track-G — service-link file-aggregated edges. Each link contributes one
+     * cross-file edge from the call-site file (service_calls.file_id) to the
+     * handler-symbol's file. Used by the module clusterer to surface
+     * client→handler dependencies as architecturally important.
+     */
+    fileServiceLinkEdgeWeights(): Array<{
+        from: number;
+        to: number;
+        weight: number;
+    }>;
+    /** All file ids + their language + rel path — feeds the clusterer. */
+    listFileSummaries(): Array<{
+        id: number;
+        relPath: string;
+        language: string;
+        role: string;
+    }>;
+    /**
+     * Replace the modules / module_members / module_edges tables with the
+     * provided clustering. Atomic — wrapped in a single transaction so a
+     * partial write can't leave inconsistent membership.
+     */
+    replaceModules(modules: Array<{
+        label: string;
+        sizeFiles: number;
+        sizeSymbols: number;
+        primaryLanguage: string | null;
+        cohesion: number;
+        centrality: number;
+        fileIds: number[];
+    }>, edges: Array<{
+        fromIndex: number;
+        toIndex: number;
+        kind: string;
+        weight: number;
+    }>, algorithm?: string): void;
+    hasModulesData(): boolean;
+    countModules(): number;
+    listModules(options?: {
+        limit?: number;
+        sortBy?: 'centrality' | 'size' | 'label';
+    }): Array<{
+        id: number;
+        label: string;
+        sizeFiles: number;
+        sizeSymbols: number;
+        primaryLanguage: string | null;
+        cohesion: number;
+        centrality: number;
+    }>;
+    getModuleById(id: number): {
+        id: number;
+        label: string;
+        sizeFiles: number;
+        sizeSymbols: number;
+        primaryLanguage: string | null;
+        cohesion: number;
+        centrality: number;
+    } | null;
+    /** Module label → row. Used by CLI/MCP module lookups by name. */
+    getModuleByLabel(label: string): {
+        id: number;
+        label: string;
+        sizeFiles: number;
+        sizeSymbols: number;
+        primaryLanguage: string | null;
+        cohesion: number;
+        centrality: number;
+    } | null;
+    /**
+     * Files in a module, sorted by file path. Returns empty array if the
+     * module id doesn't exist or modules haven't been built.
+     */
+    listModuleMembers(moduleId: number, limit?: number): Array<{
+        fileId: number;
+        path: string;
+        relPath: string;
+        language: string;
+        role: string;
+    }>;
+    /** Top symbols (by PageRank) inside a module. Useful for "what does this module own?" */
+    listModuleTopSymbols(moduleId: number, limit?: number): SymbolRow[];
+    /** Module containing a file id, or null when the file has no membership row. */
+    moduleForFile(fileId: number): {
+        id: number;
+        label: string;
+    } | null;
+    /**
+     * Cross-module dependency edges. Direction is configurable:
+     *   - 'out' (default) → modules this one depends on (from = moduleId)
+     *   - 'in'            → modules that depend on this one (to = moduleId)
+     * Aggregates across all edge kinds; the kind is preserved per row.
+     */
+    moduleDependencies(moduleId: number, options?: {
+        direction?: 'in' | 'out';
+        limit?: number;
+    }): Array<{
+        moduleId: number;
+        label: string;
+        kind: string;
+        weight: number;
+    }>;
+    /**
+     * Raw 'tests' edges into a specific symbol id — id-scoped so short-name
+     * siblings (`Alpha.run` / `Beta.run`) don't share a behavioral contract.
+     * Returns the test-side caller info (name, file, line) so the ranker can
+     * compute path-convention and naming-convention signals without
+     * re-fetching.
+     *
+     * The id-based filter is correct because `synthesizeTestEdges()` now
+     * preserves the source call edge's resolved `to_id` verbatim instead of
+     * re-resolving via `WHERE name = edges.to_name LIMIT 1` (which collapsed
+     * same-short-name symbols).
+     */
+    directTestEdgesForId(symbolId: number, limit?: number): Array<{
+        callerId: number;
+        callerName: string;
+        callerQualifiedName: string | null;
+        callerKind: string;
+        callerFile: string;
+        callerLineStart: number;
+        callerLineEnd: number;
+        edgeLine: number;
+        assertionCount: number;
+    }>;
+    /**
+     * Count how many distinct routes have this symbol as their resolved handler.
+     * Used by seer_risk for the "route exposure" signal.
+     */
+    routesForHandler(symbolId: number): Array<{
+        method: string;
+        path: string;
+        framework: string;
+    }>;
+    /** Distinct config keys read inside a symbol's body. */
+    configKeysForSymbol(symbolId: number): Array<{
+        key: string;
+        source: string;
+        line: number;
+    }>;
+    /**
+     * For each call edge OUT of a symbol, return the callee's module id (when
+     * resolved). Used by seer_risk for the "module-boundary crossing" signal.
+     * NULL module ids are filtered out — those are external/unresolved calls.
+     */
+    calleeModulesOf(symbolId: number): Array<{
+        calleeId: number;
+        moduleId: number;
+    }>;
+    /**
+     * For each file id, return the symbols that match the given line ranges.
+     * Used by `detect_changes` to compute the blast radius of a diff.
+     */
+    symbolsTouchingLines(fileId: number, lineRanges: Array<[number, number]>): SymbolRow[];
+    /**
+     * Record (or refresh) a SCIP import. Returns the row id. UNIQUE on
+     * (path, sha256) — if the same file with the same content is re-imported,
+     * the existing row is kept (the caller's idempotency guarantee).
+     */
+    recordScipImport(scipPath: string, sha256: string, tool: string | null, projectRoot: string | null, symbolCount: number, refCount: number): number;
+    /**
+     * Has this exact SCIP file (by sha) been imported already? Lets callers
+     * short-circuit a re-parse on no-op CI re-runs.
+     */
+    hasScipImport(scipPath: string, sha256: string): boolean;
+    /** Listing for `seer_scip_imports` / the bundle manifest. */
+    listScipImports(): Array<{
+        id: number;
+        path: string;
+        sha256: string;
+        tool: string | null;
+        projectRoot: string | null;
+        importedAt: number;
+        symbolCount: number;
+        refCount: number;
+    }>;
+    /**
+     * Insert (or upsert) a SCIP-sourced symbol. Returns the row id. Uses
+     * (file_id, qualified_name, line_start, kind) as the dedup key when the
+     * existing row was also SCIP-sourced — we never delete tree-sitter rows.
+     * Tree-sitter rows with the same identifier and overlapping line range are
+     * marked 'scip-merge' (precision confirmed by SCIP) instead of being
+     * duplicated, so the agent-facing default lens stays compact.
+     *
+     * `scipImportId` is the `scip_imports.id` row this symbol came from — it
+     * gets persisted on both fresh inserts and merge updates so a later
+     * `clearScipProvenance(path)` can scope its wipe to a single layer instead
+     * of nuking every SCIP row in the DB.
+     */
+    insertOrMergeScipSymbol(fileId: number, def: SymbolDef, scipImportId: number): {
+        id: number;
+        merged: boolean;
+    };
+    /**
+     * Insert a SCIP-sourced reference edge. `to_id` is set immediately because
+     * SCIP gives us precise targets — no need for the same-file/imported/global
+     * fallback resolver used for tree-sitter call edges.
+     *
+     * `scipImportId` ties the edge to the contributing SCIP layer so per-layer
+     * wipes are clean.
+     */
+    insertScipEdge(fromSymbolId: number, toSymbolId: number, toName: string, kind: string, line: number, scipImportId: number): void;
+    /**
+     * Wipe SCIP-sourced rows so a fresh import can replace them. Tree-sitter
+     * rows are preserved; only the rows that came from the specified SCIP layer
+     * are touched.
+     *
+     *   - scipPath omitted → ALL SCIP layers are wiped (every scip-provenance
+     *     row is dropped, every scip-merge row demoted to tree-sitter, and
+     *     the scip_imports table emptied). Useful for "I want my baseline
+     *     back."
+     *   - scipPath provided → only rows linked to scip_imports.id for that
+     *     path are touched. Sibling layers stay intact. This is what
+     *     importScip() calls before re-ingesting the same path, so a
+     *     multi-layer setup (rust+ts SCIPs) stays correct on partial refresh.
+     */
+    clearScipProvenance(scipPath?: string): number;
+    /** Provenance breakdown for `seer_health` / `seer_stats`. */
+    getProvenanceCounts(): {
+        symbols: Record<string, number>;
+        edges: Record<string, number>;
+    };
+    /** Set a symbol's shape_hash. NULL clears it. Persisted as INTEGER. */
+    setShapeHash(symbolId: number, hash: bigint | null): void;
+    /**
+     * Fetch all symbols that have a non-null shape_hash. Used as the candidate
+     * pool for duplicate detection. Returns minimal fields to keep the working
+     * set small on huge codebases.
+     */
+    listSymbolsWithShapeHash(opts?: {
+        minLoc?: number;
+        includeTests?: boolean;
+        limit?: number;
+    }): Array<{
+        id: number;
+        name: string;
+        qualifiedName: string | null;
+        kind: string;
+        filePath: string;
+        lineStart: number;
+        lineEnd: number;
+        loc: number | null;
+        shapeHash: bigint;
+    }>;
+    /** v7 read-flag accessor for downstream features that need to gate on it. */
+    hasV7(): boolean;
+    /**
+     * Are there function-like symbols (kind function/method/constructor, role
+     * not 'declaration', loc >= 4) that don't yet have a shape_hash? Used by
+     * the indexer to decide whether to run buildShapeHashes() on a cached
+     * re-run — when a pre-v7 DB migrates to v7, every existing row still has
+     * shape_hash NULL even though the file is "cached" (its content hash
+     * didn't change), so the normal graphChanged predicate misses the
+     * backfill. This check catches that.
+     */
+    hasMissingShapeHashes(minLoc?: number): boolean;
+    getStats(): StatsRow;
+    /** Direct access to the underlying DB for niche callers (history indexer). */
+    rawDb(): DatabaseSync;
+    begin(): void;
+    commit(): void;
+    rollback(): void;
+    close(): void;
+}
+/**
+ * Build a stable symbol-history key for a symbol. The shape is
+ * `kind:qualified_name` — coarse on purpose so a function rename within a
+ * file collapses history to the new name (we'd rather lose precision than
+ * lose history entirely when extractors disagree about parameter shape).
+ *
+ * Future: include parameter arity or signature-hash for overload distinction.
+ */
+export declare function makeSymbolKey(kind: string, qualifiedName: string): string;
+/**
+ * Build an FTS5 MATCH expression from a free-text query. Strategy:
+ *   - lower-case
+ *   - split on whitespace and identifier punctuation
+ *   - quote each non-empty token and OR them together with `*` for prefix
+ *
+ * Empty / invalid → null (the caller falls back to LIKE).
+ */
+export declare function ftsQuery(input: string): string | null;
+//# sourceMappingURL=store.d.ts.map