@titan-design/code-graph 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 import { Db, Migration } from '@titan-design/store-sqlite';
-import { Tree } from 'web-tree-sitter';
+import { Extractor, ParsedFile } from '@titan-design/code-parser';
+export { Extractor, ParsedFile, getLanguageFromPath, getSupportedLanguages, parseFile, shouldIncludeFile } from '@titan-design/code-parser';
 import { Project } from 'ts-morph';
+import { c as CoEditPair, C as ChurnEntry, a as ChurnWindow } from './change-coupling-CyqHgRsm.js';
+import { Embedder } from '@titan-design/embed';
 
 type NodeKind = "package" | "module" | "file" | "symbol" | "external";
 type EdgeKind = "imports" | "re-exports" | "calls" | "extends" | "implements" | "references" | "depends-on";
-type IdAliasReason = "rename" | "move" | "merge";
+/** `requalify` maps a bare-name symbol id from before index version 0.14.0 to its scope-qualified successor. */
+type IdAliasReason = "rename" | "move" | "merge" | "requalify";
 type NodeRole = "test" | "fixture" | "barrel" | "types" | "config" | "script" | "entry" | "generated" | "source";
 interface GraphNode {
     id: string;
@@ -54,6 +58,25 @@ interface FileFingerprint {
     structuralHash?: string;
 }
 
+/** One metric's values over the nodes of one kind in one snapshot; `count` excludes null values. */
+interface MetricAggregate {
+    name: string;
+    nodeKind: NodeKind;
+    count: number;
+    sum: number | null;
+    min: number | null;
+    max: number | null;
+}
+/** One node's value for one metric, joined to the node's own vocabulary columns. */
+interface TopMetricRow {
+    nodeId: string;
+    name: string;
+    kind: string;
+    role: string | null;
+    value: number | null;
+    unit: string | null;
+}
+
 interface SnapshotInsert {
     ref: string;
     commitHash?: string;
@@ -69,11 +92,18 @@ interface SnapshotInsert {
 declare class CodeGraphStore {
     readonly db: Db;
     private readonly statements;
+    private readonly targeted;
     constructor(db: Db);
     createSnapshot(input: SnapshotInsert): number;
     insertNodes(snapshotId: number, nodes: readonly GraphNode[]): void;
     insertEdges(snapshotId: number, edges: readonly GraphEdge[]): void;
     insertMetrics(snapshotId: number, metrics: readonly GraphMetric[]): void;
+    /**
+     * Replace every metric of one `name` for a snapshot in a single transaction —
+     * for an overlay such as coverage, which is re-ingested wholesale and must not
+     * accumulate stale rows across runs.
+     */
+    replaceMetricsByName(snapshotId: number, name: string, metrics: readonly GraphMetric[]): void;
     insertAliases(snapshotId: number, aliases: readonly IdAlias[]): void;
     insertFingerprints(snapshotId: number, fingerprints: readonly FileFingerprint[]): void;
     getSnapshot(id: number): SnapshotRow | null;
@@ -96,8 +126,31 @@ declare class CodeGraphStore {
         includeReferences?: boolean;
     }): GraphEdge[];
     listMetrics(snapshotId: number): GraphMetric[];
+    /** Every metric on one node, from the primary key instead of a whole-snapshot read. */
+    listMetricsForNode(snapshotId: number, nodeId: string): GraphMetric[];
+    /** Distinct metric names stored for a snapshot, ascending. */
+    listMetricNames(snapshotId: number): string[];
+    /** The highest-valued nodes for one metric, descending; `limit` defaults to 20. */
+    topByMetric(opts: {
+        snapshotId: number;
+        metric: string;
+        limit?: number;
+        kind?: string;
+    }): TopMetricRow[];
+    /** Edges into or out of one node; `references` edges are excluded unless asked, as in {@link listEdges}. */
+    listEdgesTouching(snapshotId: number, nodeId: string, opts?: {
+        includeReferences?: boolean;
+    }): GraphEdge[];
+    /** Count, sum, min, and max per metric name and node kind; pass `name` for one metric. */
+    aggregateMetrics(snapshotId: number, opts?: {
+        name?: string;
+    }): MetricAggregate[];
     listAliases(snapshotId: number): IdAlias[];
     listFingerprints(snapshotId: number): FileFingerprint[];
+    /** Drop whole snapshots. The domain tables carry no foreign key, so each is cleared by hand. */
+    deleteSnapshots(ids: readonly number[]): void;
+    vacuum(): void;
+    countRowsByTable(tables: readonly string[]): Record<string, number>;
     close(): void;
 }
 /** Open (creating if absent) a code graph database and bring it to the current schema. */
@@ -122,14 +175,37 @@ declare const KIT: {
  * `file_fingerprint` is the reuse basis the incremental indexer diffs against.
  */
 declare const DOMAIN_DDL = "\n  CREATE TABLE IF NOT EXISTS edge (\n    snapshot_id INTEGER NOT NULL,\n    src_id      TEXT NOT NULL,\n    dst_id      TEXT NOT NULL,\n    kind        TEXT NOT NULL,\n    attrs       TEXT,\n    PRIMARY KEY (snapshot_id, src_id, dst_id, kind)\n  );\n  CREATE INDEX IF NOT EXISTS idx_edge_dst ON edge(snapshot_id, dst_id);\n  CREATE INDEX IF NOT EXISTS idx_edge_kind ON edge(snapshot_id, kind);\n\n  CREATE TABLE IF NOT EXISTS metric (\n    snapshot_id INTEGER NOT NULL,\n    node_id     TEXT NOT NULL,\n    name        TEXT NOT NULL,\n    value       REAL,\n    unit        TEXT,\n    PRIMARY KEY (snapshot_id, node_id, name)\n  );\n  CREATE INDEX IF NOT EXISTS idx_metric_name ON metric(snapshot_id, name);\n\n  CREATE TABLE IF NOT EXISTS id_alias (\n    snapshot_id INTEGER NOT NULL,\n    old_id      TEXT NOT NULL,\n    new_id      TEXT NOT NULL,\n    reason      TEXT NOT NULL,\n    PRIMARY KEY (snapshot_id, old_id, new_id)\n  );\n\n  CREATE TABLE IF NOT EXISTS file_fingerprint (\n    snapshot_id     INTEGER NOT NULL,\n    file_id         TEXT NOT NULL,\n    content_hash    TEXT NOT NULL,\n    structural_hash TEXT,\n    PRIMARY KEY (snapshot_id, file_id)\n  );\n";
+/** Every table keyed by `snapshot_id`. No DDL above declares a foreign key, so dropping a snapshot walks this list. */
+declare const SNAPSHOT_SCOPED_TABLES: readonly ["node", "edge", "metric", "id_alias", "file_fingerprint"];
 declare const MIGRATIONS: Migration[];
+/** The top of this package's schema. A code graph database is never shared, so this is the top of one. */
+declare const SCHEMA_VERSION: number;
+
+interface PrunePlan {
+    keep: SnapshotRow[];
+    remove: SnapshotRow[];
+}
+interface PruneOptions {
+    keep?: number;
+    keepRefs?: readonly string[];
+}
+declare function planPrune(store: CodeGraphStore, options?: PruneOptions): PrunePlan;
+interface PruneResult {
+    plan: PrunePlan;
+    rowsBefore: Record<string, number>;
+    rowsAfter: Record<string, number>;
+    vacuumed: boolean;
+}
+declare function runPrune(store: CodeGraphStore, options?: PruneOptions & {
+    vacuum?: boolean;
+}): PruneResult;
 
 /**
  * Bumping this invalidates every reuse basis: a snapshot written by a different
- * index version is never reused, so a change to node/edge shape can never be
- * carried forward from an incompatible graph.
+ * index version is never reused, so a change to node/edge shape or to a metric's
+ * value for the same bytes can never be carried forward from an incompatible graph.
  */
-declare const INDEX_VERSION = "0.11.0";
+declare const INDEX_VERSION = "0.15.0";
 interface IndexOptions {
     /** Roots to walk. Node ids are still rooted at the git toplevel, so importers across roots share an id space. */
     paths: string[];
@@ -145,6 +221,14 @@ interface IndexOptions {
      * reason to disable it is to rebuild from scratch.
      */
     incremental?: boolean;
+    /** Git churn, recency, and ownership metrics. Defaults to `true`; history is skipped silently outside git. */
+    computeChurn?: boolean;
+    /** Primary churn window in days (default 30); scopes ownership. */
+    churnWindowDays?: number;
+    /** Windows to store churn for (default 30, 90, 180); the primary window is always included. */
+    churnWindows?: number[];
+    /** Also store an all-time `lifetime` churn and ownership window over full git history. */
+    lifetime?: boolean;
 }
 interface IndexResult {
     snapshotId: number;
@@ -170,23 +254,6 @@ interface IndexResult {
  */
 declare function indexPaths(store: CodeGraphStore, options: IndexOptions): Promise<IndexResult>;
 
-interface ParsedFile {
-    tree: Tree;
-    content: string;
-    filePath: string;
-    language: string;
-}
-interface Extractor<T> {
-    name: string;
-    extract(file: ParsedFile): T[];
-}
-
-declare function parseFile(content: string, filePath: string, language: string): Promise<ParsedFile>;
-declare function getSupportedLanguages(): string[];
-
-declare function shouldIncludeFile(filePath: string, languages: string[]): boolean;
-declare function getLanguageFromPath(filePath: string): string | null;
-
 interface LanguageExtractorOptions {
     repoRoot: string;
     tsConfigPath?: string;
@@ -293,15 +360,60 @@ declare class TsMorphGraphExtractor implements Extractor<GraphFragment> {
  */
 declare function buildFileModuleNodes(repoRoot: string, absPath: string): GraphNode[];
 
+/**
+ * C-81 — **deep AST on-pull**. Structural facts too heavy to persist at index
+ * time (class members, per-parameter types, return type) are recomputed lazily
+ * here from the working-tree source when a consumer actually pulls a target.
+ * Persisting them would bloat every symbol node and break the incremental reuse
+ * basis (inferred types embed absolute `import("…")` paths); computing on demand
+ * keeps the index lean while still answering "what are the members / params of
+ * this" for the one target being read.
+ *
+ * A single-file in-memory ts-morph project (no tsconfig, no dependency walk) —
+ * so the extraction is cheap and reads only explicit syntactic annotations.
+ */
+interface ParamInfo {
+    name: string;
+    type: string | null;
+}
+interface MemberInfo {
+    name: string;
+    memberKind: string;
+    signature: string | null;
+    isStatic: boolean;
+}
+interface DeepAst {
+    target: string;
+    kind: "file" | "symbol";
+    declarationKind: string | null;
+    signature: string | null;
+    purpose: string | null;
+    params: ParamInfo[];
+    returnType: string | null;
+    /** Class/interface members for a symbol; exported declarations for a file. */
+    members: MemberInfo[];
+    note?: string;
+}
+interface DeepAstInput {
+    /** Repo-relative file id, e.g. `src/a.ts`. */
+    filePath: string;
+    /** Absolute path to the file on disk. */
+    absPath: string;
+    /** Symbol name for a symbol target; omit for a file target. */
+    symbolName?: string;
+}
+/** Deep structural facts for one target, or null when the source is unreadable. */
+declare function computeDeepAst(input: DeepAstInput): DeepAst | null;
+
 declare function fileId(repoRoot: string, absPath: string): string;
 declare function moduleId(repoRoot: string, absPath: string): string;
 declare function parentModuleId(id: string): string | null;
 declare function packageId(name: string): string;
 declare const SYMBOL_ID_SEP = "#";
-declare function symbolId(fileId: string, exportName: string): string;
+declare function symbolId(fileId: string, qualifiedName: string): string;
 /**
  * Inverse of {@link symbolId}: split a `<fileId>#<name>` symbol id back into its
- * declaring file and export name. Returns null for an id with no separator (a
+ * declaring file and qualified name. Returns null for an id with no separator (a
  * plain file id), so callers can filter the symbol layer cleanly. `#` is illegal
  * in both posix paths and JS identifiers, so the first occurrence is the split.
  */
@@ -368,15 +480,10 @@ interface LineSpan {
     endLine: number;
 }
 /**
- * Every function/method/class a file DECLARES, mapped to its 1-based line span
- * (the model-B symbol surface, C-64, now carrying spans for C-63 coverage
- * range-containment). A superset of the file's exports: internal helpers like
- * `mergeFragments` are included so they get a `symbol` node (and, by name match,
- * their complexity + coverage) even though nothing imports them. Names come from
- * the same tree-sitter walk that computes complexity, so they never drift.
- * Anonymous declarations (a default-exported arrow, inline callbacks) contribute
- * no name and are skipped. A name declared more than once keeps its last span
- * (overloads / same-named methods are rare; range lookup still resolves most).
+ * Qualified declared names mapped to their 1-based line span (C-63 coverage
+ * range-containment). One scope binds a name once, as TypeScript and Python do,
+ * so a getter/setter pair, a Python property's accessors, and `@overload` stubs
+ * share one entry; when a qualified name repeats, the last span wins.
  */
 declare function collectDeclaredSpans(file: ParsedFile): Map<string, LineSpan>;
 /** Declared names only — the Set view over {@link collectDeclaredSpans}. */
@@ -458,6 +565,8 @@ declare function canonicalMetricName(name: string): string;
 declare function canonicalRole(name: string): NodeRole;
 declare function canonicalEdgeKind(name: string): EdgeKind;
 
+declare function detectGitToplevel(cwd: string): string | null;
+
 interface RenamePair {
     oldPath: string;
     newPath: string;
@@ -471,10 +580,85 @@ interface DetectRenamesOptions {
 }
 declare function detectGitHead(repoRoot: string): string | null;
 declare function isInsideGitRepo(repoRoot: string): boolean;
-declare function detectGitToplevel(cwd: string): string | null;
+
+/** Resolve a ref (branch, tag, sha) to its current commit sha, or null. */
+declare function resolveGitRef(repoRoot: string, ref: string): string | null;
 declare function detectRenames(options: DetectRenamesOptions): RenamePair[];
 declare function buildAliases(repoRoot: string, pairs: readonly RenamePair[]): IdAlias[];
 
+/** Snapshot attrs key naming the snapshot its id aliases were computed against; written from index version 0.15.0. */
+declare const ALIAS_BASE_ATTR = "aliasBase";
+type LineageSnapshot = Pick<SnapshotRow, "id" | "commitHash" | "attrs">;
+/** Each snapshot's alias base, or null for a root: the tree the id_alias rows form across snapshots. */
+type Lineage = ReadonlyMap<number, number | null>;
+interface LineageStep {
+    snapshotId: number;
+    /** `forward` applies the snapshot's aliases (base to snapshot); `backward` undoes them. */
+    direction: "forward" | "backward";
+}
+/**
+ * The recorded base per snapshot. A snapshot written before 0.15.0 records none,
+ * so it gets the newest earlier snapshot with a commit: the one the indexer diffed against then.
+ */
+declare function buildLineage(snapshots: readonly LineageSnapshot[]): Lineage;
+/** Steps from one snapshot to another through their nearest common base, or null when they share none. */
+declare function lineagePath(lineage: Lineage, fromId: number, toId: number, maxHops?: number): LineageStep[] | null;
+
+type AliasLoader = (snapshotId: number) => readonly IdAlias[];
+interface AliasResolution {
+    requestedId: string;
+    /** The id in the target snapshot's id space; equal to `requestedId` when nothing moved. */
+    id: string;
+    /** Each alias applied in walk order; a backward step lists the alias it undid. */
+    hops: IdAlias[];
+    /** `move` when any hop changed directory, otherwise the last hop's reason; absent without hops. */
+    reason?: IdAliasReason;
+}
+interface AliasChain {
+    fromSnapshotId: number | null;
+    toSnapshotId: number;
+    /** False when the snapshots share no alias base; only the target's own aliases apply then, as before 0.15.0. */
+    connected: boolean;
+    steps: readonly LineageStep[];
+    resolve(id: string): string;
+    trace(id: string): AliasResolution;
+}
+interface AliasChainInput {
+    lineage: Lineage;
+    loadAliases: AliasLoader;
+    /** Null resolves an id from any ancestor of `to`. */
+    from: number | null;
+    to: number;
+    maxHops?: number;
+}
+/** Carry node ids from one snapshot into another across every rename between them. */
+declare function createAliasChain(input: AliasChainInput): AliasChain;
+
+interface AliasChainOptions {
+    maxHops?: number;
+}
+interface ResolveAliasOptions extends AliasChainOptions {
+    /** The snapshot the id was read in; omitted, the id may come from any ancestor of the target. */
+    fromSnapshotId?: number;
+}
+interface PriorSnapshotOptions {
+    /** Only snapshots older than this id count; omitted, every snapshot does. */
+    before?: number;
+    /** A git checkout to resolve `ref` in; without it only the snapshot's `ref` label matches. */
+    repoRoot?: string;
+}
+/** The alias-base tree over every snapshot in the store. */
+declare function loadLineage(store: CodeGraphStore): Lineage;
+/** Carry node ids from `fromSnapshotId` into `toSnapshotId` through every alias between them, in either direction. */
+declare function aliasChain(store: CodeGraphStore, fromSnapshotId: number | null, toSnapshotId: number, options?: AliasChainOptions): AliasChain;
+/** Resolve an id to its form in `toSnapshotId`: `a.ts` renamed to `b.ts` then `c.ts` resolves to `c.ts`. */
+declare function resolveAlias(store: CodeGraphStore, id: string, toSnapshotId: number, options?: ResolveAliasOptions): AliasResolution;
+/**
+ * The newest snapshot a ref denotes: first the snapshot of the commit git resolves
+ * `ref` to (with `repoRoot`), else the newest snapshot whose `ref` label is `ref`.
+ */
+declare function priorSnapshotForRef(store: CodeGraphStore, ref: string, options?: PriorSnapshotOptions): SnapshotRow | null;
+
 declare function computeMetrics(nodes: readonly GraphNode[], edges: readonly GraphEdge[]): GraphMetric[];
 
 /**
@@ -494,6 +678,73 @@ declare const SOURCE_METRIC_NAMES: ReadonlySet<string>;
  */
 declare function computeSourceMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string, symbolNamesByFile?: ReadonlyMap<string, ReadonlySet<string>>): GraphMetric[];
 
+/** How a test↔source pairing was inferred. */
+type LinkMethod = "path" | "coedit";
+interface TestSourceLink {
+    /** Node id of the test file. */
+    testId: string;
+    /** Node id of the (non-test) file it covers. */
+    sourceId: string;
+    method: LinkMethod;
+}
+interface LinkTestsOptions {
+    /** Minimum co-edit count for a pass-2 (coedit) link. Default 2. */
+    minCoEditCount?: number;
+}
+/**
+ * Two-pass test↔source linker. Pass 1 pairs each test file with non-test files
+ * matching its path conventions (high confidence). Pass 2 supplements tests
+ * left unpaired by pass 1 with their strongest co-edited non-test partner from
+ * change-coupling. Handles orphan tests (no pairing), orphan/untested sources
+ * (no incoming link), and one-to-many pairings (a test matching several
+ * sources, or a source covered by several tests).
+ */
+declare function linkTestsToSources(nodes: readonly GraphNode[], coEditPairs: readonly CoEditPair[], options?: LinkTestsOptions): TestSourceLink[];
+/**
+ * Per-source coverage breadth: how many distinct test files link to each
+ * covered source. Emitted only for sources with at least one linked test.
+ */
+declare function testCoverageCountMetrics(links: readonly TestSourceLink[]): GraphMetric[];
+/** Map each covered source to the set of test files that link to it. */
+declare function groupTestsBySource(links: readonly TestSourceLink[]): Map<string, Set<string>>;
+
+interface HistoryMetricsOptions {
+    /** Primary window: scopes ownership. Default 30. */
+    churnWindowDays?: number;
+    /** Windows to store churn and recency for; default {@link DEFAULT_CHURN_WINDOWS}, primary always included. */
+    churnWindows?: number[];
+    /** Also store an all-time `lifetime` window over full git history. */
+    includeLifetime?: boolean;
+    /** Epoch seconds that windows end at; defaults to the current time. */
+    nowEpoch?: number;
+}
+/** Windows the dashboard switcher offers; churn is stored for each by default. */
+declare const DEFAULT_CHURN_WINDOWS: number[];
+/** De-duped, ascending windows including the primary, with `lifetime` last (widest) when requested. */
+declare function resolveChurnWindows(requested: number[] | undefined, primaryWindow: number, includeLifetime: boolean): ChurnWindow[];
+interface LoadedHistory {
+    metrics: GraphMetric[];
+    /** Churn entries inside the primary window, which also scopes test-coverage linking and ownership. */
+    primaryEntries: readonly ChurnEntry[];
+}
+/** {@link buildHistoryMetrics} plus the primary-window entries it read; null when git or history is unavailable. */
+declare function loadHistoryMetrics(nodes: Iterable<GraphNode>, idRoot: string, options?: HistoryMetricsOptions): LoadedHistory | null;
+interface TestCoverageOwnershipOptions {
+    /** Window named in the metric suffix. Default 30. */
+    windowDays?: ChurnWindow;
+    /** Coverage threshold for bus factor (default 0.5 = 50% of churn). */
+    busFactorThreshold?: number;
+}
+/**
+ * Bus-factor / top-author-share of the *test coverage* for each source, keyed
+ * on the source node. Aggregates churn authorship across all test files linked
+ * to a source (via the two-pass linker) and summarises it the same way as
+ * production ownership — so a file can read as well-spread on production code
+ * yet a single-author silo on its tests (or vice versa). Emitted only for
+ * sources with at least one linked test that has churn in the window.
+ */
+declare function computeTestCoverageOwnership(entries: readonly ChurnEntry[], links: readonly TestSourceLink[], options?: TestCoverageOwnershipOptions): GraphMetric[];
+
 interface IndexerMetricsInput {
     nodes: Map<string, GraphNode>;
     edges: Map<string, GraphEdge>;
@@ -502,6 +753,8 @@ interface IndexerMetricsInput {
     /** Source metrics carried forward verbatim for reused (unchanged) files. */
     reusedSourceMetrics: GraphMetric[];
     idRoot: string;
+    /** Git-history metrics (churn, recency, ownership); omitted means none. */
+    history?: HistoryMetricsOptions;
 }
 /**
  * Assemble the metric set for a snapshot: graph-wide degree metrics over the
@@ -510,12 +763,324 @@ interface IndexerMetricsInput {
  * reused source metrics is recomputed over the full set, so the result matches a
  * full index regardless of how much was reused.
  *
- * Git-history metrics (churn, ownership, change coupling, test coverage) are
- * deliberately absent here; they are a separate analysis layer, deferred with
- * the rest of codewatch's analyses.
+ * Git-history metrics come from the path-based engine in `./history/` through
+ * the `history-metrics.ts` adapter. Test-coverage metrics run with or without it.
  */
 declare function buildIndexerMetrics(input: IndexerMetricsInput): GraphMetric[];
 
+/**
+ * Function-local dead-code metrics (C-65 Phase 1). Pure functions of one file's
+ * bytes — the same class as the source metrics in source-metrics.ts — so they
+ * ride the content-hash incremental reuse gate. Kept in their own module (not
+ * appended to source-metrics.ts) so the already-churn-hot source-metrics.ts is
+ * not touched; the reuse machinery folds these names in alongside
+ * SOURCE_METRIC_NAMES (see incremental.ts) and index-metrics.ts computes them
+ * fresh for (re)parsed files.
+ */
+declare const DEAD_CODE_METRIC_NAMES: ReadonlySet<string>;
+/**
+ * Per-file dead-code metrics for TypeScript files. Emitted sparsely — only when
+ * a count is > 0 — so a clean file adds no rows (a full index and an incremental
+ * re-index therefore produce the identical metric set). Non-TypeScript files are
+ * skipped for now.
+ */
+declare function computeDeadCodeMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string): GraphMetric[];
+
+/**
+ * Growth-risk / scaling-smell metrics (C-66 Phase 2). Cheap, function-local
+ * *heuristics* — NOT Big-O or a proven complexity class (real asymptotic
+ * inference is undecidable; see the roadmap's hard NO). Pure functions of one
+ * file's bytes, so they ride the content-hash incremental reuse gate, folded
+ * into the carry-forward set in incremental.ts alongside the source/dead-code
+ * metric names. Emitted sparsely (only when a smell is present).
+ */
+declare const GROWTH_RISK_METRIC_NAMES: ReadonlySet<string>;
+/**
+ * Per-file growth-risk metrics for TS/Python files, all SMELLS not bounds:
+ * - `loop_depth` — max *lexical* loop nesting (triple-nested → 3), emitted at
+ *   depth ≥ 2 (depth-2 loops over two *different* collections are actually linear).
+ * - `recursive_functions` — named functions that call themselves directly.
+ * - `search_in_loop` — linear-scan method calls (`.includes`/`.find`/…) inside a
+ *   loop (an O(n) scan per iteration; `.includes` on a `Set` is O(1)).
+ * All emitted sparsely (only when present). Non-TS/Python files are skipped.
+ */
+declare function computeGrowthRiskMetrics(files: readonly ParsedFile[], fileIdOf: (filePath: string) => string): GraphMetric[];
+
+/**
+ * Coverage is a whole-suite DYNAMIC artifact — a function of *which tests ran*,
+ * not of any file's bytes — so it must NOT ride the content-hash reuse gate. It
+ * is emitted as a `coverage_pct` metric that is deliberately absent from every
+ * *_METRIC_NAMES reuse set, so an incremental index never carries it forward: a
+ * later index produces a snapshot with NO coverage until re-ingested. That is the
+ * overlay semantics — coverage is attached to the snapshot it was measured
+ * against and never inferred for another.
+ */
+declare const COVERAGE_METRIC_NAME = "coverage_pct";
+/** Minimal Istanbul `coverage-final.json` shape we read (function-level). */
+interface IstanbulFn {
+    loc: {
+        start: {
+            line: number;
+        };
+        end: {
+            line: number;
+        };
+    };
+}
+interface IstanbulFileCoverage {
+    fnMap: Record<string, IstanbulFn>;
+    /** Per-function hit counts, keyed to fnMap ids. */
+    f: Record<string, number>;
+}
+type IstanbulCoverage = Record<string, IstanbulFileCoverage>;
+/** A symbol node's 1-based line span, for range-containment attribution. */
+interface SymbolSpan {
+    id: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * Attribute an Istanbul coverage report to graph nodes as `coverage_pct` metrics:
+ * one per covered FILE (covered functions / total functions), and one per SYMBOL
+ * a covered function maps into by RANGE containment (symbol spans) — matching
+ * by range, not name, so anonymous/mangled Istanbul function names are handled.
+ * A symbol spanning several functions (a class) reports its methods' coverage
+ * ratio. Files Istanbul reports but the graph doesn't know are skipped.
+ */
+declare function attributeCoverage(coverage: IstanbulCoverage, fileIdOf: (absPath: string) => string | null, symbolsByFile: ReadonlyMap<string, readonly SymbolSpan[]>): GraphMetric[];
+
+/** Metric-name suffix for a window: `30d`, `180d`, or `lifetime`. */
+declare function windowSuffix(window: ChurnWindow): string;
+/**
+ * Age-discount metrics: `recency_{w}` = min(1, age/w) for each file that churned
+ * in window `w`, plus one window-independent `file_age_days` per file. Multiplying
+ * a hotspot score by recency stops a young file's burst of churn from reading as
+ * decay. Recency is emitted (as 1) even when the age is unknown, so a rule that
+ * needs every hotspot factor is never silently disabled; `file_age_days` only when known.
+ */
+declare function computeRecencyWindows(firstSeen: ReadonlyMap<string, number>, churnedIdsByWindow: ReadonlyMap<ChurnWindow, ReadonlySet<string>>, nowEpoch: number): GraphMetric[];
+
+interface PageRankOptions {
+    /** Per-node teleport weight. Unset or empty → uniform teleport across all nodes. */
+    personalization?: ReadonlyMap<string, number>;
+    /** Probability of following an edge vs teleporting (default 0.85). */
+    damping?: number;
+    /** L1 convergence threshold (default 1e-6). */
+    tolerance?: number;
+    /** Cap on power-iteration steps (default 100). */
+    maxIterations?: number;
+    /** Per-kind edge weight; missing kinds default to 1.0. */
+    edgeWeights?: Partial<Record<EdgeKind, number>>;
+}
+interface PageRankRow {
+    nodeId: string;
+    score: number;
+}
+interface PageRankResult {
+    /** Sorted descending by score; ties broken by node id ascending. */
+    rows: PageRankRow[];
+    iterations: number;
+    converged: boolean;
+}
+/** Edge weight used by PageRank for a given edge kind, honoring user overrides. */
+declare function getEdgeWeight(kind: EdgeKind, overrides?: Partial<Record<EdgeKind, number>>): number;
+declare function computePageRank(nodes: readonly GraphNode[], edges: readonly GraphEdge[], options?: PageRankOptions): PageRankResult;
+
+interface RelevanceOptions {
+    /** Probability of following an edge vs teleporting back to the seeds (default 0.85). */
+    damping?: number;
+    /** Per-kind edge weight override, forwarded to PageRank. */
+    edgeWeights?: PageRankOptions["edgeWeights"];
+}
+/**
+ * C-89 — **seeded (personalized) PageRank as a relevance-to-target proximity
+ * measure** (Aider RepoMap-style). The teleport vector is concentrated on
+ * `seedIds`, so the stationary distribution scores every node by how tightly it
+ * couples to the seeds through the resolved dependency graph: near neighbours
+ * score high, decaying with graph distance. This is "relevance to what I'm
+ * looking at," distinct from global PageRank centrality ("globally famous"),
+ * which stays the no-seed cold path.
+ *
+ * The edge set is **symmetrized** (each edge added in both directions) so
+ * relevance flows to a target's callers AND its dependencies — a purely forward
+ * walk from the seed would only reach what the seed depends on, never who
+ * depends on it. Edge kind (and therefore weight) is preserved on the reversed
+ * copy, so a heavier `calls` edge stays heavier in both directions.
+ *
+ * Returns a Map from node id to relevance score (seeds included). An empty seed
+ * set returns an empty map — callers then fall back to global centrality.
+ */
+declare function computeRelevance(nodes: readonly GraphNode[], edges: readonly GraphEdge[], seedIds: readonly string[], options?: RelevanceOptions): Map<string, number>;
+
+/**
+ * Symbol-level change coupling (C-60). Decomposes a god-file the file-level
+ * coupling view rolls up as one blob (e.g. `types.ts`) into *which symbol* is
+ * used where. Built on the C-53 `references` edge substrate: `src` is the
+ * importing file, `dst` is the imported symbol node id (`<fileId>#<name>`).
+ *
+ * Two slices, both pure functions of the assembled reference edge set (a
+ * whole-graph rollup like utilization/PageRank, sound under incremental reuse
+ * since it reads the reassembled edges, not a per-file cache):
+ *
+ * - **Slice C — per-symbol consumers**: invert the edges by `dst`, giving the
+ *   set of files that import each symbol. Directly answers "what IN this file is
+ *   used where"; covers span-less types/consts that a git-hunk approach cannot.
+ * - **Slice B — co-import coupling**: group edges by `src`, and every pair of
+ *   symbols co-imported by the same file is a coupling pair. Two symbols that
+ *   are always imported together travel together — structural (used-together),
+ *   drift-free coupling, as opposed to the temporal (changed-together) git
+ *   co-edit signal.
+ */
+/** The minimal shape of a `references` edge this module consumes. */
+interface ReferenceEdgeLite {
+    /** Importing file id. */
+    srcId: string;
+    /** Imported symbol node id (`<fileId>#<name>`). */
+    dstId: string;
+}
+/** One symbol's consumer set (Slice C). */
+interface SymbolConsumers {
+    symbolId: string;
+    /** Declaring file, parsed from the symbol id. */
+    fileId: string;
+    /** Export name. */
+    name: string;
+    /** Distinct importing file ids, sorted. */
+    consumers: string[];
+}
+/** A pair of symbols co-imported by the same file (Slice B). */
+interface SymbolCouplingPair {
+    aId: string;
+    aFile: string;
+    aName: string;
+    bId: string;
+    bFile: string;
+    bName: string;
+    /** Distinct files that import both symbols. */
+    coImports: number;
+    /** True when the two symbols are declared in different files. */
+    crossFile: boolean;
+}
+interface SymbolCouplingOptions {
+    /** Skip pairs co-imported by fewer than this many files. Default 2. */
+    minCoImports?: number;
+    /**
+     * Skip importing files that reference more than this many distinct symbols —
+     * a wide barrel-style importer would otherwise explode into O(n²) noise
+     * pairs, mirroring change-coupling's large-commit guard. Default 40.
+     */
+    largeImporterThreshold?: number;
+}
+/**
+ * Group reference edges by imported symbol, yielding each symbol's distinct
+ * consuming files (Slice C). Sorted by consumer count desc, then symbol id, so
+ * the most broadly-depended-on exports lead.
+ */
+declare function computeSymbolConsumers(edges: readonly ReferenceEdgeLite[]): SymbolConsumers[];
+/**
+ * Every pair of symbols co-imported by the same file becomes a coupling pair,
+ * counted by how many distinct files co-import them (Slice B). Wide importers
+ * are dropped to keep the pairing near-linear. Sorted by co-import count desc,
+ * cross-file pairs preferred at a tie (they are the actionable ones — a
+ * same-file pair is just cohesion within one module).
+ */
+declare function computeSymbolCoupling(edges: readonly ReferenceEdgeLite[], options?: SymbolCouplingOptions): SymbolCouplingPair[];
+
+/**
+ * Per-package and per-pair structural quality metrics, plus an overall
+ * Newman-Girvan modularity Q for the package partition.
+ *
+ * Operates on a barrel-resolved edge set by default: edges that land on a
+ * file with role="barrel" are rewritten to land on the underlying files
+ * the barrel re-exports from (transitively). The intent is to measure the
+ * real dependency surface, not the re-export plumbing.
+ *
+ * See C-8 task notes for the design rationale and empirical calibration
+ * data from the 2026-05-21 codewatch dogfood.
+ */
+interface PartitionQualityInput {
+    /** Logical packages — at minimum needs an id. */
+    packages: ReadonlyArray<{
+        id: string;
+    }>;
+    /** Package id → list of file ids assigned to that package. */
+    fileByPackage: ReadonlyMap<string, ReadonlyArray<string>>;
+    /** All file/module/external nodes for the snapshot. Used to identify role="barrel". */
+    nodes: readonly GraphNode[];
+    /** All edges for the snapshot. */
+    edges: readonly GraphEdge[];
+    /**
+     * When true, edges landing on a barrel file are resolved through its
+     * re-export chain to the underlying source files. The cheap implementation
+     * fans each barrel import into N synthetic edges (one per re-export
+     * target), which over-attributes — a single `import { x } from "./pkg"`
+     * becomes N edges as if every re-export were used. Default false until
+     * a weighted or symbol-tracking version is available.
+     */
+    resolveBarrels?: boolean;
+}
+type PackageFlag = "weak-boundary";
+type PairFlag = "tight" | "moderate" | "none";
+type PackageLayer = "top" | "middle" | "foundation";
+interface PackageStats {
+    pkgId: string;
+    fileCount: number;
+    internalEdges: number;
+    outgoingEdges: number;
+    incomingEdges: number;
+    /** internal / (internal + outgoing) — higher = more self-contained. */
+    cohesion: number;
+    /** outgoing / (outgoing + incoming) — Martin's I metric at the package level. */
+    instability: number;
+    /**
+     * Abstractness proxy A ∈ [0,1]: share of the package's files with role
+     * "types" (dedicated type/interface definitions). codewatch has no
+     * symbol-level abstract/concrete counts, so this file-role ratio stands in
+     * for Martin's A. Enables the instability×abstractness main-sequence plot.
+     */
+    abstractness: number;
+    layer: PackageLayer;
+    flags: PackageFlag[];
+}
+interface PairCoupling {
+    from: string;
+    to: string;
+    edges: number;
+    /** edges / files(from) — fraction of from-side files contributing dependencies into `to`. */
+    intensity: number;
+    flag: PairFlag;
+}
+interface PartitionQualityResult {
+    modularityQ: number;
+    totalEdges: number;
+    perPackage: PackageStats[];
+    pairCoupling: PairCoupling[];
+    /** Total raised flags across packages + pairs (excluding "moderate"). */
+    flagsCount: number;
+}
+declare function computePartitionQuality(input: PartitionQualityInput): PartitionQualityResult;
+/**
+ * Invert a package→files bucket map into a file→package lookup, skipping the
+ * empty-string "unassigned" bucket. Shared by partition-quality and the CLI's
+ * arch/wiki package rollups, which all need the same file→package direction.
+ */
+declare function invertBuckets(fileByPackage: ReadonlyMap<string, ReadonlyArray<string>>): Map<string, string>;
+
+/**
+ * PageRank over one snapshot's file-level graph (symbol nodes and `references`
+ * edges excluded, as codewatch's `graph relevant` reads it). Pass
+ * `personalization` to seed the walk toward target node ids.
+ */
+declare function snapshotPageRank(store: CodeGraphStore, snapshotId: number, options?: PageRankOptions): PageRankResult;
+/** Relevance of every file-level node to `seedIds`, as codewatch's `graph context` computes it. */
+declare function snapshotRelevance(store: CodeGraphStore, snapshotId: number, seedIds: readonly string[], options?: RelevanceOptions): Map<string, number>;
+/** The snapshot's `references` edges: importing file to imported symbol. */
+declare function snapshotReferenceEdges(store: CodeGraphStore, snapshotId: number): ReferenceEdgeLite[];
+/** Per-symbol consumer files for one snapshot. */
+declare function snapshotSymbolConsumers(store: CodeGraphStore, snapshotId: number): SymbolConsumers[];
+/** Co-import symbol coupling pairs for one snapshot. */
+declare function snapshotSymbolCoupling(store: CodeGraphStore, snapshotId: number, options?: SymbolCouplingOptions): SymbolCouplingPair[];
+
 /**
  * The free-function reading surface named in the package API. Each delegates to
  * the store's method of the same name, so a caller that only reads a snapshot
@@ -528,5 +1093,343 @@ declare function listEdges(store: CodeGraphStore, snapshotId: number, opts?: {
     includeReferences?: boolean;
 }): GraphEdge[];
 declare function listMetrics(store: CodeGraphStore, snapshotId: number): GraphMetric[];
+declare function listMetricsForNode(store: CodeGraphStore, snapshotId: number, nodeId: string): GraphMetric[];
+declare function listEdgesTouching(store: CodeGraphStore, snapshotId: number, nodeId: string, opts?: {
+    includeReferences?: boolean;
+}): GraphEdge[];
+declare function aggregateMetrics(store: CodeGraphStore, snapshotId: number, opts?: {
+    name?: string;
+}): MetricAggregate[];
+
+/** The `unit` a metric row is stored with; every row of one metric name carries the same unit. */
+type MetricUnit = "count" | "lines" | "ratio" | "days" | "percent";
+/** How file values combine into a directory; `none` means no rollup reproduces the group's true value. */
+type MetricRollup = "sum" | "max" | "mean" | "none";
+/** Which way is worse, for ranking and colouring; `neutral` makes no value judgement. */
+type MetricDirection = "higher-worse" | "lower-worse" | "neutral";
+/** A missing row reads as zero (a sparse writer's floor) or is left out of means, percentiles, and ranks. */
+type MetricAbsence = "zero" | "exclude";
+/** The code-graph module that writes the metric, for provenance. */
+type MetricSource = "degree" | "source-metrics" | "lcom" | "dead-code" | "growth-risk" | "history" | "test-linker" | "coverage";
+interface MetricDescriptor {
+    /** The stored name, or a template such as `churn_{w}` when {@link windowed} is set. */
+    name: string;
+    unit: MetricUnit;
+    /** Node kinds the writer attaches this metric to. */
+    appliesTo: readonly NodeKind[];
+    rollup: MetricRollup;
+    direction: MetricDirection;
+    absent: MetricAbsence;
+    source: MetricSource;
+    description: string;
+    /** Set on templates: `{w}` in `name` and `description` stands for a window such as `30d` or `lifetime`. */
+    windowed?: true;
+    /** Set on a resolved windowed descriptor: the window its name carries. */
+    window?: string;
+}
+
+/** Every metric name code-graph writes, with windowed names as `{w}` templates. */
+declare const METRIC_CATALOGUE: readonly MetricDescriptor[];
+
+/** The descriptor for a stored metric name, resolving windowed names such as `churn_90d`; null when uncatalogued. */
+declare function describeMetric(name: string): MetricDescriptor | null;
+/** Descriptors for a set of stored names, in the order given; uncatalogued names are returned separately. */
+declare function describeMetrics(names: Iterable<string>): {
+    described: MetricDescriptor[];
+    unknown: string[];
+};
+
+type Severity = "error" | "warning";
+interface MetricMaxRule {
+    type: "metric-max";
+    id: string;
+    metric: string;
+    max: number;
+    kind?: NodeKind;
+    severity?: Severity;
+    exclude?: string[];
+    excludeRoles?: NodeRole[];
+}
+interface MetricMinRule {
+    type: "metric-min";
+    id: string;
+    metric: string;
+    min: number;
+    kind?: NodeKind;
+    severity?: Severity;
+    exclude?: string[];
+    excludeRoles?: NodeRole[];
+}
+interface MetricProductMaxRule {
+    type: "metric-product-max";
+    id: string;
+    metrics: string[];
+    max: number;
+    kind?: NodeKind;
+    severity?: Severity;
+    exclude?: string[];
+    excludeRoles?: NodeRole[];
+}
+interface ForbidImportRule {
+    type: "forbid-import";
+    id: string;
+    from: string;
+    to: string;
+    severity?: Severity;
+}
+interface LayeredDepsRule {
+    type: "layered-deps";
+    id: string;
+    layers: string[][];
+    severity?: Severity;
+}
+interface NoInternalOnlyBarrelsRule {
+    type: "no-internal-only-barrels";
+    id: string;
+    /** Path prefixes marking package roots; node ids carry no intrinsic package membership. */
+    packageRoots: string[];
+    severity?: Severity;
+    /** Globs or substrings to skip, such as CLI bin entries the role classifier calls barrels. */
+    exclude?: string[];
+}
+type CheckRule = MetricMaxRule | MetricMinRule | MetricProductMaxRule | ForbidImportRule | LayeredDepsRule | NoInternalOnlyBarrelsRule;
+interface CheckRulesFile {
+    rules: CheckRule[];
+}
+interface CheckViolation {
+    ruleId: string;
+    severity: Severity;
+    nodeId: string;
+    message: string;
+    metric?: string;
+    value?: number;
+    threshold?: number;
+    destinationId?: string;
+    isCarryover?: boolean;
+}
+interface CheckResult {
+    snapshotId: number;
+    baselineSnapshotId?: number;
+    rulesEvaluated: number;
+    nodesEvaluated: number;
+    violations: CheckViolation[];
+    newErrors: number;
+    newWarnings: number;
+    carryoverErrors: number;
+    carryoverWarnings: number;
+    passed: boolean;
+}
+
+/** The three whole-snapshot reads rule evaluation needs; any store with them can be checked. */
+type RuleStore = Pick<CodeGraphStore, "listNodes" | "listEdges" | "listMetrics">;
+
+interface RunChecksOptions {
+    snapshotId: number;
+    rules: readonly CheckRule[];
+    baselineSnapshotId?: number;
+}
+declare function runChecks(store: CodeGraphStore, options: RunChecksOptions): CheckResult;
+/** Every rule's violations in one snapshot with no baseline; needs only the three whole-snapshot reads. */
+declare function snapshotViolations(store: RuleStore, snapshotId: number, rules: readonly CheckRule[]): CheckViolation[];
+/** Identity of a violation across snapshots: severity, value and message may change, the key does not. */
+declare function violationKey(v: CheckViolation): string;
+/** {@link violationKey} with both node ids carried into another snapshot's id space; unmoved ids key as before. */
+declare function rebasedViolationKey(v: CheckViolation, resolve: (id: string) => string): string;
+
+/** Glob when the pattern has a `*` (`**` crosses directories, `*` stays in a segment); otherwise a case-sensitive substring. */
+declare function patternToRegex(pattern: string): RegExp;
+declare function compilePatterns(patterns: readonly string[] | undefined): RegExp[];
+declare function matchesAny(value: string, patterns: readonly RegExp[]): boolean;
+
+interface ValidateRulesOptions {
+    /** Called with a human-readable message when a deprecated alias is healed. */
+    onWarn?: (message: string) => void;
+}
+declare function validateRules(input: unknown, options?: ValidateRulesOptions): readonly CheckRule[];
+
+/** A snapshot id, or a ref name resolved to that ref's newest snapshot. */
+type SnapshotSpec = number | string;
+interface CheckSnapshotOptions {
+    snapshot: SnapshotSpec;
+    rules: readonly CheckRule[];
+    baseline?: SnapshotSpec;
+}
+interface CheckSnapshotResult {
+    snapshot: SnapshotRow;
+    baselineSnapshot?: SnapshotRow;
+    result: CheckResult;
+}
+declare function resolveSnapshot(store: CodeGraphStore, spec: SnapshotSpec): SnapshotRow;
+/** Check one snapshot against a rule set, marking violations already present in the baseline as carryover. */
+declare function checkSnapshot(store: CodeGraphStore, options: CheckSnapshotOptions): CheckSnapshotResult;
+/** Read and validate a `check.json` rules file; deprecated aliases heal through `onWarn`. */
+declare function loadCheckRules(path: string, options?: ValidateRulesOptions): Promise<readonly CheckRule[]>;
+
+interface MetricDelta {
+    nodeId: string;
+    name: string;
+    before: number | null;
+    after: number | null;
+    delta: number | null;
+}
+interface NodeRename {
+    oldId: string;
+    newId: string;
+    reason: IdAliasReason;
+    node: GraphNode;
+}
+interface GraphDiffSummary {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+    addedNodes: number;
+    removedNodes: number;
+    renamedNodes: number;
+    unchangedNodes: number;
+    addedEdges: number;
+    removedEdges: number;
+    metricChanges: number;
+}
+interface GraphDiff {
+    summary: GraphDiffSummary;
+    addedNodes: GraphNode[];
+    removedNodes: GraphNode[];
+    renamedNodes: NodeRename[];
+    addedEdges: GraphEdge[];
+    removedEdges: GraphEdge[];
+    metricDeltas: MetricDelta[];
+}
+
+interface DiffSnapshotsOptions {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+}
+/**
+ * Structural diff of two snapshots. Ids follow the alias chain between them, across
+ * every rename in between, so a move is not a delete plus an add.
+ */
+declare function diffSnapshots(store: CodeGraphStore, options: DiffSnapshotsOptions): GraphDiff;
+
+interface UnchangedViolation {
+    from: CheckViolation;
+    to: CheckViolation;
+    delta: number | null;
+}
+interface CheckDiff {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+    rulesEvaluated: number;
+    newViolations: CheckViolation[];
+    resolvedViolations: CheckViolation[];
+    unchanged: UnchangedViolation[];
+    worsened: UnchangedViolation[];
+    improved: UnchangedViolation[];
+}
+interface DiffCheckResultsOptions {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+    rules: readonly CheckRule[];
+}
+/**
+ * Run the rules on both snapshots and bucket each violation as new, resolved, or
+ * unchanged (worsened or improved by value). From-side ids follow the alias chain
+ * into the to-snapshot, so a moved file's violations stay unchanged.
+ */
+declare function diffCheckResults(store: CodeGraphStore, options: DiffCheckResultsOptions): CheckDiff;
+
+interface EmbeddableSymbol {
+    id: string;
+    name: string;
+    file: string;
+    signature: string;
+    purpose?: string;
+    text: string;
+    textHash: string;
+}
+interface EmbedCoverage {
+    /** Embeddable exported symbols in the snapshot. */
+    symbols: number;
+    /** How many symbols have a stored vector for this model. */
+    embedded: number;
+    /** How many carry docstring purpose text (where recall is strongest). */
+    withPurpose: number;
+}
+interface EmbedSnapshotResult extends EmbedCoverage {
+    model: string;
+    /** Unique new texts sent to the embedder (symbols can share a text). */
+    newlyEmbedded: number;
+    /** Symbols whose vector was already stored (content-addressed cache hits). */
+    reused: number;
+}
+/** Outcome of the non-fatal indexing pass: a down backend is reported, never thrown. */
+type EmbedAttempt = {
+    ok: true;
+    result: EmbedSnapshotResult;
+} | {
+    ok: false;
+    model: string;
+    error: string;
+};
+interface SimilarCandidate {
+    id: string;
+    name: string;
+    file: string;
+    signature: string;
+    purpose?: string;
+    /** Cosine similarity to the query, in [-1, 1]. */
+    score: number;
+}
+interface SimilarResult {
+    query: string;
+    model: string;
+    coverage: EmbedCoverage;
+    candidates: SimilarCandidate[];
+}
+/** Query prefixes are the embedder's to apply; configure them with its `prefixes` option. */
+interface FindSimilarOptions {
+    limit?: number;
+}
+
+/** Mirrors the gate harness: purpose text is appended to the signature when present. */
+declare function buildEmbedText(signature: string, purpose?: string | null): string;
+declare function hashEmbedText(text: string): string;
+/**
+ * The embeddable corpus of a snapshot: exported symbols that carry a signature,
+ * excluding test/fixture/generated code (matching the validated gate corpus).
+ */
+declare function listEmbeddableSymbols(store: CodeGraphStore, snapshotId: number): EmbeddableSymbol[];
+
+/** The blob_cache namespace for symbol vectors; the model column holds `embedder.model`, which names the vector space including its prefixes. */
+declare const SYMBOL_EMBEDDING_NAMESPACE = "code-graph/symbol-embedding";
+interface CachedEmbedResult {
+    /** L2-normalized vectors for every input text, keyed by its text hash. */
+    byHash: Map<string, number[]>;
+    /** Hashes that had no stored vector and were embedded on this call. */
+    newHashes: Set<string>;
+}
+/**
+ * Embed texts through the content-addressed store: only texts whose hash has
+ * no vector for this model reach the embedder; new vectors are normalized and
+ * persisted batch by batch so the next call (or a retry after a failure) is a cache hit.
+ */
+declare function embedTextsCached(store: CodeGraphStore, embedder: Embedder, texts: readonly string[]): Promise<CachedEmbedResult>;
+
+/**
+ * Precompute capability embeddings for a snapshot. Only texts whose hash has no
+ * stored vector are sent to the embedder, so re-runs and unchanged symbols cost
+ * nothing: the content-addressed store is the incremental-reuse mechanism.
+ */
+declare function embedSnapshot(store: CodeGraphStore, snapshotId: number, embedder: Embedder): Promise<EmbedSnapshotResult>;
+/**
+ * The post-index pass. A backend failure (ollama down, model missing) must not
+ * fail the index: the snapshot is already persisted and valid without vectors.
+ */
+declare function tryEmbedSnapshot(store: CodeGraphStore, snapshotId: number, embedder: Embedder): Promise<EmbedAttempt>;
+/**
+ * The query-time "about to write X: does it exist?" surface. Embeds the query
+ * (an intent sentence, a pseudo-signature, or both as `sig -- intent`), ranks
+ * the snapshot's embedded symbols by cosine similarity, and returns the top-K
+ * with coverage so the caller can weigh how much of the repo was searchable.
+ */
+declare function findSimilarCapability(store: CodeGraphStore, snapshotId: number, query: string, embedder: Embedder, opts?: FindSimilarOptions): Promise<SimilarResult>;
 
-export { ALL_ROLES, CodeGraphStore, DOMAIN_DDL, type EdgeKind, type Extractor, type FileFingerprint, type GraphEdge, type GraphFragment, type GraphMetric, type GraphNode, INDEX_VERSION, type IdAlias, type IdAliasReason, type IndexOptions, type IndexResult, KIT, LanguageExtractor, type LanguageExtractorOptions, type LineSpan, MIGRATIONS, type NodeKind, type NodeRole, type ParsedFile, PythonGraphExtractor, type ReadFile, type ReuseBasis, SOURCE_METRIC_NAMES, SYMBOL_ID_SEP, type SnapshotInsert, type SnapshotRow, type SourceLanguage, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, annotateRoles, buildAliases, buildFileModuleNodes, buildIndexerMetrics, canonicalEdgeKind, canonicalMetricName, canonicalRole, classifyRole, collectDeclaredNames, collectDeclaredSpans, computeMetrics, computeRoleHints, computeSourceMetrics, detectGitHead, detectGitToplevel, detectRenames, edgeWeight, externalId, fileId, getLanguageFromPath, getSupportedLanguages, hashContent, indexPaths, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, listEdges, listMetrics, listNodes, loadGeneratedPatterns, moduleId, openCodeGraph, packageId, parentModuleId, parseFile, parseSymbolId, pruneDanglingReferences, readSourceFiles, resolveBarrelEdges, shouldIncludeFile, structuralSignature, symbolId, walkSourceFiles };
+export { ALIAS_BASE_ATTR, ALL_ROLES, type AliasChain, type AliasChainInput, type AliasChainOptions, type AliasLoader, type AliasResolution, COVERAGE_METRIC_NAME, type CachedEmbedResult, type CheckDiff, type CheckResult, type CheckRule, type CheckRulesFile, type CheckSnapshotOptions, type CheckSnapshotResult, type CheckViolation, CodeGraphStore, DEAD_CODE_METRIC_NAMES, DEFAULT_CHURN_WINDOWS, DOMAIN_DDL, type DeepAst, type DeepAstInput, type DiffCheckResultsOptions, type DiffSnapshotsOptions, type EdgeKind, type EmbedAttempt, type EmbedCoverage, type EmbedSnapshotResult, type EmbeddableSymbol, type FileFingerprint, type FindSimilarOptions, type ForbidImportRule, GROWTH_RISK_METRIC_NAMES, type GraphDiff, type GraphDiffSummary, type GraphEdge, type GraphFragment, type GraphMetric, type GraphNode, type HistoryMetricsOptions, INDEX_VERSION, type IdAlias, type IdAliasReason, type IndexOptions, type IndexResult, type IstanbulCoverage, KIT, LanguageExtractor, type LanguageExtractorOptions, type LayeredDepsRule, type LineSpan, type Lineage, type LineageSnapshot, type LineageStep, type LinkMethod, type LinkTestsOptions, type LoadedHistory, METRIC_CATALOGUE, MIGRATIONS, type MemberInfo, type MetricAbsence, type MetricAggregate, type MetricDelta, type MetricDescriptor, type MetricDirection, type MetricMaxRule, type MetricMinRule, type MetricProductMaxRule, type MetricRollup, type MetricSource, type MetricUnit, type NoInternalOnlyBarrelsRule, type NodeKind, type NodeRename, type NodeRole, type PackageFlag, type PackageLayer, type PackageStats, type PageRankOptions, type PageRankResult, type PageRankRow, type PairCoupling, type PairFlag, type ParamInfo, type PartitionQualityInput, type PartitionQualityResult, type PriorSnapshotOptions, type PruneOptions, type PrunePlan, type PruneResult, PythonGraphExtractor, type ReadFile, type ReferenceEdgeLite, type RelevanceOptions, type ResolveAliasOptions, type ReuseBasis, type RuleStore, type RunChecksOptions, SCHEMA_VERSION, SNAPSHOT_SCOPED_TABLES, SOURCE_METRIC_NAMES, SYMBOL_EMBEDDING_NAMESPACE, SYMBOL_ID_SEP, type Severity, type SimilarCandidate, type SimilarResult, type SnapshotInsert, type SnapshotRow, type SnapshotSpec, type SourceLanguage, type SymbolConsumers, type SymbolCouplingOptions, type SymbolCouplingPair, type SymbolSpan, type TestCoverageOwnershipOptions, type TestSourceLink, type TopMetricRow, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, type UnchangedViolation, type ValidateRulesOptions, aggregateMetrics, aliasChain, annotateRoles, attributeCoverage, buildAliases, buildEmbedText, buildFileModuleNodes, buildIndexerMetrics, buildLineage, canonicalEdgeKind, canonicalMetricName, canonicalRole, checkSnapshot, classifyRole, collectDeclaredNames, collectDeclaredSpans, compilePatterns, computeDeadCodeMetrics, computeDeepAst, computeGrowthRiskMetrics, computeMetrics, computePageRank, computePartitionQuality, computeRecencyWindows, computeRelevance, computeRoleHints, computeSourceMetrics, computeSymbolConsumers, computeSymbolCoupling, computeTestCoverageOwnership, createAliasChain, describeMetric, describeMetrics, detectGitHead, detectGitToplevel, detectRenames, diffCheckResults, diffSnapshots, edgeWeight, embedSnapshot, embedTextsCached, externalId, fileId, findSimilarCapability, getEdgeWeight, groupTestsBySource, hashContent, hashEmbedText, indexPaths, invertBuckets, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, lineagePath, linkTestsToSources, listEdges, listEdgesTouching, listEmbeddableSymbols, listMetrics, listMetricsForNode, listNodes, loadCheckRules, loadGeneratedPatterns, loadHistoryMetrics, loadLineage, matchesAny, moduleId, openCodeGraph, packageId, parentModuleId, parseSymbolId, patternToRegex, planPrune, priorSnapshotForRef, pruneDanglingReferences, readSourceFiles, rebasedViolationKey, resolveAlias, resolveBarrelEdges, resolveChurnWindows, resolveGitRef, resolveSnapshot, runChecks, runPrune, snapshotPageRank, snapshotReferenceEdges, snapshotRelevance, snapshotSymbolConsumers, snapshotSymbolCoupling, snapshotViolations, structuralSignature, symbolId, testCoverageCountMetrics, tryEmbedSnapshot, validateRules, violationKey, walkSourceFiles, windowSuffix };