@wrongstack/tools 1.0.1 → 1.0.3

package/dist/codebase-index/atlas-types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The shapes the Codebase Atlas projection emits.
+ *
+ * They live apart from the code that builds them so that a renderer can name
+ * what it renders without importing the builder: `atlas-projection` produces
+ * these and calls `atlas-export` to render them, and `atlas-export` needs the
+ * types but must never reach back for the builder. Declaring them here is what
+ * keeps that a one-way edge instead of a module cycle.
+ *
+ * Everything here is plain data — no imports, no behaviour. `atlas-projection`
+ * re-exports the whole set, so consumers keep importing from there.
+ */
+export interface AtlasSymbol {
+    name: string;
+    kind: string;
+    line: number;
+}
+export interface AtlasFile {
+    path: string;
+    rank: number;
+    inDeg: number;
+    outDeg: number;
+    package: string;
+    symbols: AtlasSymbol[];
+    /** Concept-layer summary. Omitted entirely when the layer has not run. */
+    concept?: string;
+}
+export interface AtlasPackage {
+    name: string;
+    files: number;
+    /** Highest-ranked file in the package. */
+    hub: string;
+    rank: number;
+    /** Subsystem summary for this package, when the concept layer derived one. */
+    summary?: string;
+}
+/**
+ * A package-level dependency, aggregated from the reference graph.
+ *
+ * Only the package level is projected. File-level edges would be tens of
+ * thousands of rows — a diff nobody can read and a file nobody can render,
+ * for a level of detail the index itself answers better on demand.
+ */
+export interface AtlasEdge {
+    from: string;
+    to: string;
+    weight: number;
+    refType: string;
+}
+export interface AtlasDocument {
+    schema: number;
+    counts: {
+        files: number;
+        symbols: number;
+        packages: number;
+    };
+    packages: AtlasPackage[];
+    edges: AtlasEdge[];
+    files: AtlasFile[];
+}
+export interface AtlasManifest {
+    schema: number;
+    /**
+     * `files`/`symbols` are the index's own totals, for display.
+     *
+     * `tracked` is the size of the file set the digest was computed over — the
+     * only number a freshness check may compare its own file set against. The
+     * two can differ (a file with no symbols is tracked but may not count
+     * towards `files`), and comparing across them reported phantom additions.
+     */
+    counts: {
+        files: number;
+        symbols: number;
+        tracked: number;
+    };
+    /**
+     * sha-256 over every indexed file's `path\0contentHash`, sorted. Catches a
+     * change anywhere in the repository, including files the atlas does not
+     * itself carry.
+     */
+    digest: string;
+    /** Per-file content hashes, for the files the atlas describes. */
+    files: Record<string, string>;
+}
+export interface AtlasProjection {
+    document: AtlasDocument;
+    manifest: AtlasManifest;
+    markdown: string;
+}
+//# sourceMappingURL=atlas-types.d.ts.map

package/dist/codebase-index/background-indexer.d.ts

@@ -26,10 +26,11 @@
  *    for the TUI status chip and the search/stats tools' gating.
  */
 import { type CircuitSnapshot } from './circuit-breaker.js';
+import type { ContextResult } from './context-retrieval.js';
 import { type IncomingCallsResult, type OutgoingCallsResult } from './index-service.js';
 import { type ProjectIndexServerClientHealth, type ProjectIndexServerConnectionState, type ProjectIndexServerShutdownResult } from './project-server-client.js';
 import type { CodeMapGraph, IndexResult, IndexStats } from './schema.js';
-import type { CallRefsOpArgs, FileGraphOpArgs, SearchOpArgs, SearchOpResult, StatsOpArgs, SymbolGraphOpArgs } from './worker-protocol.js';
+import type { CallRefsOpArgs, ContextOpArgs, FileGraphOpArgs, SearchOpArgs, SearchOpResult, StatsOpArgs, SymbolGraphOpArgs, VectorSearchOpArgs, VectorSearchOpResult } from './worker-protocol.js';
 /** True once the first full-project index has completed (success or failure). */
 export declare function isIndexReady(): boolean;
 /**
@@ -89,14 +90,13 @@ export declare function enqueueReindex(opts: {
      * Per-project trailing coalescing window. After a file's debounce timer
      * fires, the ready batch stays open for this long before flushing. Any file
      * whose timer fires within the window joins the same batch and resets the
-     * timer (sliding). Default: 50ms. Set to 0 to flush immediately after each
-     * debounce timer fires (legacy behavior — staggered bursts don't coalesce).
+     * timer (sliding). Default: 50ms; set to 0 for immediate flush.
      */
     coalesceWindowMs?: number | undefined;
     /** Watchdog timeout per file. Default: 30s. */
     timeoutMs?: number | undefined;
     onError?: ((err: unknown) => void) | undefined;
-}): void;
+}): Promise<void>;
 /** Cancel all pending debounced reindexes. For teardown / tests. */
 export declare function cancelPendingReindexes(): void;
 /**
@@ -115,6 +115,17 @@ export declare function codebaseIndexStats(args: StatsOpArgs, opts?: {
     timeoutMs?: number | undefined;
     signal?: AbortSignal | undefined;
 }): Promise<IndexStats>;
+/**
+ * Personalised retrieval — the single call that answers "which files does this
+ * task touch?", served by the same per-project index process so the wiring
+ * graph is built once per generation rather than once per query.
+ */
+export declare function codebaseContext(args: ContextOpArgs): Promise<ContextResult>;
+/**
+ * Nearest files to an already-embedded query vector. The model stays in the
+ * caller's process; only numbers cross IPC.
+ */
+export declare function codebaseVectorSearch(args: VectorSearchOpArgs): Promise<VectorSearchOpResult>;
 /** Package dependency graph, served by the same per-project index process. */
 export declare function packageGraphService(args: StatsOpArgs): Promise<CodeMapGraph>;
 /** File dependency graph, served by the same per-project index process. */

package/dist/codebase-index/codebase-context-tool.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `codebase-context` tool — one call that answers "which files does this task
+ * touch, and what is in them?".
+ *
+ * The index already exposed the ingredients: `codebase-search` finds symbols
+ * by name, `codebase-skeleton` shows a file's shape, `codebase-incoming-calls`
+ * finds callers. Composing them was left to the model, which meant re-deriving
+ * the same chain on every task and spending several round trips on plumbing.
+ * This tool runs the composition server-side: lexical search seeds a
+ * personalised PageRank walk over the reference graph, and what comes back is
+ * the ranked file set with the declarations that matter in each.
+ *
+ * It deliberately returns signatures and line numbers rather than source. The
+ * point is to make the subsequent `read` land in the right place, not to
+ * replace it — inlining bodies here would spend the caller's context on code
+ * they may not need.
+ */
+import type { Tool } from '@wrongstack/core/types';
+import type { ContextEntry } from './context-retrieval.js';
+import type { EmbeddingPort } from './embedding-pass.js';
+export interface CodebaseContextInput {
+    /** What you are trying to do or understand, in plain words. */
+    query: string;
+    /** Files to return. Defaults to 12, capped at 50. */
+    limit?: number | undefined;
+    /** Declarations shown per file. Defaults to 4, capped at 20. */
+    symbolsPerFile?: number | undefined;
+    /** Restrict results to a project-relative path prefix. */
+    pathPrefix?: string | undefined;
+}
+export interface CodebaseContextOutput {
+    query: string;
+    entries: ContextEntry[];
+    /** Lexical hits that seeded the walk. */
+    seedCount: number;
+    /** Semantic hits that also seeded it. Zero without an embedding model. */
+    semanticSeedCount: number;
+    /** Files the walk reached before truncation to `limit`. */
+    totalCandidates: number;
+    /**
+     * `ok` — a ranked answer. `no-index` — nothing indexed yet.
+     * `no-matches` — the index exists but the query matched nothing.
+     * `unranked` — symbols exist but no reference graph, so results are lexical
+     * only. `error` — the lookup itself failed; see `error`.
+     */
+    indexStatus: 'ok' | 'no-index' | 'no-matches' | 'unranked' | 'error';
+    /** True when a cached answer from a previous generation was served. */
+    stale?: boolean | undefined;
+    error?: string | undefined;
+}
+/** Install (or clear) the query-time embedding model. */
+export declare function setContextQueryEmbedder(port: EmbeddingPort | undefined): void;
+export declare const codebaseContextTool: Tool<CodebaseContextInput, CodebaseContextOutput>;
+//# sourceMappingURL=codebase-context-tool.d.ts.map

package/dist/codebase-index/concept-enrichment.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The concept-layer enrichment pass.
+ *
+ * Walks the index's files most-central-first and asks a model, once per file,
+ * what the file is for. The answer is a short plain-English summary plus a
+ * **crux**: the line span that actually carries the file's meaning. A summary
+ * can drift from the truth; a pointer into the source cannot, so the two are
+ * always stored together.
+ *
+ * ## Why this is a separate pass
+ *
+ * Model calls take seconds. `runIndexerAtomic` is a SQLite write transaction —
+ * holding one open across thousands of network round trips would block every
+ * other writer for the duration and roll the whole thing back on the first
+ * failure. So enrichment runs on its own, outside the indexer, writing each
+ * result as it arrives.
+ *
+ * ## Why it is affordable
+ *
+ * `files.content_hash` already exists and is exactly the right cache key: a
+ * file whose bytes have not changed is never re-sent. A first pass over this
+ * repository is thousands of calls; every pass after it is only the files that
+ * actually changed. That is the difference between a one-off cost and a
+ * recurring one.
+ *
+ * ## Why it never takes the caller down
+ *
+ * Enrichment is an optional layer over a working index. A model that refuses,
+ * times out, or returns something unparseable degrades one file's summary — it
+ * is recorded in `errors` and the walk continues. Cancellation is honoured
+ * between files, and everything already written stays written.
+ */
+import { type IndexStore } from './writer.js';
+/** What the summariser is given about one file. */
+export interface SummarizeFileInput {
+    /** Project-relative path, for the model's benefit. */
+    file: string;
+    /** Absolute path, if the summariser wants to read more itself. */
+    absolutePath: string;
+    language: string;
+    /** File source, already truncated to {@link MAX_SOURCE_CHARS}. */
+    source: string;
+    /** Whether `source` was cut short. */
+    truncated: boolean;
+    /** Declarations the index recorded, as orientation. */
+    declarations: ReadonlyArray<{
+        name: string;
+        kind: string;
+        line: number;
+    }>;
+    /** A previous, now-outdated summary, when one exists. */
+    staleSummary?: string | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface SummarizeFileResult {
+    /** One or two sentences on what the file is for. */
+    summary: string;
+    /** 1-based inclusive line span of the load-bearing lines. */
+    cruxStart?: number | undefined;
+    cruxEnd?: number | undefined;
+    /** Model identifier, recorded so a later pass can tell what produced this. */
+    model?: string | undefined;
+}
+export interface SummarizeSubsystemInput {
+    /** Package or directory label. */
+    name: string;
+    files: ReadonlyArray<{
+        file: string;
+        summary: string;
+        rank: number;
+    }>;
+    signal?: AbortSignal | undefined;
+}
+export interface SummarizeSubsystemResult {
+    summary: string;
+    /**
+     * Other subsystem names this one relates to, with a relation from the closed
+     * vocabulary. Unknown relations and unknown targets are dropped by the caller.
+     */
+    relations?: ReadonlyArray<{
+        to: string;
+        relation: string;
+    }> | undefined;
+    model?: string | undefined;
+}
+/**
+ * The host-supplied model transport.
+ *
+ * Injected rather than imported: producing a summary needs a configured
+ * provider and the model-tier policy, both of which live in the host. This
+ * mirrors how SAGE takes `getLlmCall` — `packages/tools` stays free of
+ * provider wiring, and a host that supplies no port simply gets no concepts.
+ */
+export interface SummarizerPort {
+    describeFile(input: SummarizeFileInput): Promise<SummarizeFileResult | null>;
+    describeSubsystem?(input: SummarizeSubsystemInput): Promise<SummarizeSubsystemResult | null>;
+}
+/** Source sent per file. Enough for a summary; short enough to stay cheap. */
+export declare const MAX_SOURCE_CHARS = 12000;
+/** Crux span ceiling. Graft uses twelve lines; longer stops being a pointer. */
+export declare const MAX_CRUX_LINES = 12;
+export declare const DEFAULT_CONCURRENCY = 5;
+/** Summary length ceiling, so one verbose model cannot bloat the layer. */
+export declare const MAX_SUMMARY_CHARS = 400;
+export interface EnrichOptions {
+    /** Stop after this many files. The natural way to sample the cost first. */
+    maxFiles?: number | undefined;
+    /** Files summarised in parallel. */
+    concurrency?: number | undefined;
+    /** Re-summarise files whose summary is already current. */
+    force?: boolean | undefined;
+    /** Also derive the subsystem layer, when the port supports it. */
+    subsystems?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+    onProgress?: ((done: number, total: number) => void) | undefined;
+}
+export interface EnrichResult {
+    /** Files sent to the model. */
+    summarised: number;
+    /** Files skipped because their stored summary already matched. */
+    cached: number;
+    /** Files the model declined or failed on. */
+    failed: number;
+    /** Concepts marked stale before the walk started. */
+    markedStale: number;
+    /** Concepts dropped because their file left the index. */
+    pruned: number;
+    subsystems: number;
+    durationMs: number;
+    errors: string[];
+}
+/**
+ * Run one enrichment pass.
+ *
+ * `relativeOf` is injected for the same reason the retrieval walk takes it —
+ * the caller owns what "project-relative" means, and this module stays free of
+ * path policy.
+ */
+export declare function enrichConcepts(store: IndexStore, port: SummarizerPort, relativeOf: (file: string) => string, options?: EnrichOptions): Promise<EnrichResult>;
+/** Reported when a project has no index to enrich. */
+export type ConceptIndexMissing = {
+    indexed: false;
+};
+/**
+ * Enrich a project's concept layer, owning the store lifetime so callers
+ * outside this package never touch `indexStorePool`.
+ *
+ * Refuses to run without an existing index: opening a store CREATES the
+ * database, and spending money summarising an empty index helps nobody.
+ */
+export declare function enrichProjectConcepts(projectRoot: string, port: SummarizerPort, options?: EnrichOptions & {
+    indexDir?: string | undefined;
+}): Promise<EnrichResult | ConceptIndexMissing>;
+//# sourceMappingURL=concept-enrichment.d.ts.map

package/dist/codebase-index/context-retrieval.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Personalised retrieval — "which files does this task touch?"
+ *
+ * Lexical search proposes, the graph disposes. A BM25/FTS query produces a set
+ * of seed symbols with scores; those scores become the restart distribution of
+ * a personalised PageRank walk over the wiring graph. The walk then surfaces
+ * what the seeds are structurally attached to: the interface a matched
+ * function implements, the module every matched call site imports, the store
+ * behind the handler that matched by name.
+ *
+ * This is the piece that turns the index from a set of primitives an agent has
+ * to compose by hand — search, then skeleton, then incoming-calls, then read —
+ * into one answer. The composition was previously re-derived by the model on
+ * every task, at the cost of several round trips and a great deal of judgement
+ * spent on plumbing rather than on the problem.
+ *
+ * What comes back is declarations, not source: file, relevance, and the
+ * matching symbols with their signatures and line numbers. Reading the actual
+ * code stays a deliberate `read` — the point is to make that read land in the
+ * right place the first time.
+ */
+import type { IndexStore } from './writer.js';
+/** One symbol worth showing inside a returned file. */
+export interface ContextSymbol {
+    name: string;
+    kind: string;
+    line: number;
+    signature: string;
+    /** True when lexical search matched this symbol directly. */
+    seed: boolean;
+}
+/** One file in the answer, most relevant first. */
+export interface ContextEntry {
+    /** Project-relative POSIX path. */
+    file: string;
+    /** Relevance to this query, normalised so the top entry is 1.0. */
+    relevance: number;
+    /** Whether any symbol here matched the query lexically. */
+    matched: boolean;
+    symbols: ContextSymbol[];
+}
+export interface ContextResult {
+    query: string;
+    entries: ContextEntry[];
+    /** Lexical hits that seeded the walk. Zero means nothing matched. */
+    seedCount: number;
+    /** Semantic hits that also seeded it. */
+    semanticSeedCount: number;
+    /** Files the walk reached before truncation to `limit`. */
+    totalCandidates: number;
+    indexStatus: 'ok' | 'no-index' | 'no-matches' | 'unranked';
+}
+export interface ContextOptions {
+    query: string;
+    /**
+     * Files a semantic search already matched, with their cosine scores.
+     *
+     * Supplied by the caller rather than computed here because the embedding
+     * model lives host-side — functions cannot cross the daemon's IPC boundary,
+     * so only the resulting file scores travel. These become additional restart
+     * mass, letting a query phrased in the problem's vocabulary reach code whose
+     * identifiers never use those words.
+     */
+    vectorFiles?: ReadonlyArray<{
+        file: string;
+        score: number;
+    }> | undefined;
+    /** Files to return. */
+    limit?: number | undefined;
+    /** Symbols to show per file. */
+    symbolsPerFile?: number | undefined;
+    /** Restrict results to files under this project-relative prefix. */
+    pathPrefix?: string | undefined;
+}
+/**
+ * Lexical hits used as restart mass. More seeds make the walk broader and
+ * blunter; this is enough to cover a multi-word query's separate senses
+ * without letting a common token dominate.
+ */
+export declare const SEED_LIMIT = 40;
+export declare const DEFAULT_LIMIT = 12;
+export declare const DEFAULT_SYMBOLS_PER_FILE = 4;
+/**
+ * Run the personalised walk and group the winners into files.
+ *
+ * Returns an empty result rather than throwing whenever the index cannot
+ * answer — an unbuilt index and a query nobody matches are ordinary states,
+ * and `indexStatus` says which one happened.
+ */
+export declare function retrieveContext(store: IndexStore, projectRoot: string, indexDir: string | undefined, options: ContextOptions, relativeOf: (file: string) => string): ContextResult;
+//# sourceMappingURL=context-retrieval.d.ts.map

package/dist/codebase-index/embedding-pass.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The semantic embedding pass.
+ *
+ * Embeds one vector per file so the index can answer questions phrased in the
+ * problem's vocabulary rather than the code's — "where do we back off after a
+ * 429" instead of `retryAfterMsFromHeaders`.
+ *
+ * ## What gets embedded, and why it is the file
+ *
+ * A bare declaration is poor material for an embedding: `function resolve(id:
+ * string): Widget` carries almost nothing a lexical index does not already
+ * have, and BM25 over FTS5 already matches it better. What carries meaning is
+ * the concept layer's description of what a file is *for*, so that is the text
+ * this pass embeds, falling back to the file's declaration names when no
+ * summary exists yet.
+ *
+ * That also makes it eight times cheaper than a symbol-level pass on this
+ * repository — eight thousand files against sixty-six thousand symbols.
+ *
+ * ## Why it is a pass and not part of indexing
+ *
+ * Model inference is asynchronous and batched. The indexer's write path is a
+ * synchronous SQLite transaction; running inference inside it would hold a
+ * write lock open across thousands of inferences. The older char-trigram
+ * embedding could live there precisely because it was neither of those things
+ * — and it was also not semantic, which is why it is being superseded rather
+ * than extended.
+ *
+ * ## Why the vectors never silently mix
+ *
+ * Two models produce incomparable spaces. The provider id is stored with every
+ * row and checked before a pass; a change wipes the table and re-embeds rather
+ * than leaving half the index in one space and half in another.
+ */
+import { type IndexStore } from './writer.js';
+/**
+ * The host-supplied embedding model.
+ *
+ * Structurally identical to the `EmbeddingProvider` that
+ * `packages/vector-memory` already defines, so its transformers-backed
+ * implementation satisfies this without an adapter. Injected rather than
+ * imported for the same reason the summariser is: `packages/tools` must not
+ * depend on an optional native model runtime.
+ */
+export interface EmbeddingPort {
+    /** Stable id including the model and quantisation. Changing it re-embeds. */
+    readonly id: string;
+    /** Vector length. Must not change for a given `id`. */
+    readonly dimensions: number;
+    /** Embed a batch. Must return exactly one vector per input, in order. */
+    embed(texts: string[]): Promise<Float32Array[]>;
+}
+/** Texts sent per inference call. */
+export declare const DEFAULT_BATCH_SIZE = 16;
+/** Ceiling on embedded text. Beyond this a summary is not a summary. */
+export declare const MAX_EMBED_CHARS = 2000;
+export interface EmbedOptions {
+    /** Stop after this many files. */
+    maxFiles?: number | undefined;
+    batchSize?: number | undefined;
+    /** Re-embed even when the stored text hash still matches. */
+    force?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+    onProgress?: ((done: number, total: number) => void) | undefined;
+}
+export interface EmbedResult {
+    embedded: number;
+    /** Files whose embedded text was unchanged. */
+    cached: number;
+    /** Vectors dropped because their file left the index. */
+    pruned: number;
+    /** True when a provider change forced a full re-embed. */
+    providerChanged: boolean;
+    /** Files with no summary, embedded from their declaration names instead. */
+    fromDeclarations: number;
+    durationMs: number;
+    errors: string[];
+}
+/**
+ * Run one embedding pass. Never throws: an inference failure costs that batch
+ * its vectors, is recorded in `errors`, and the walk continues.
+ */
+export declare function embedFiles(store: IndexStore, port: EmbeddingPort, relativeOf: (file: string) => string, options?: EmbedOptions): Promise<EmbedResult>;
+/** Reported when a project has no index to embed. */
+export type EmbedIndexMissing = {
+    indexed: false;
+};
+/**
+ * Embed a project's files, owning the store lifetime so callers outside this
+ * package never touch `indexStorePool`. Refuses to run without an index.
+ */
+export declare function embedProjectFiles(projectRoot: string, port: EmbeddingPort, options?: EmbedOptions & {
+    indexDir?: string | undefined;
+}): Promise<EmbedResult | EmbedIndexMissing>;
+//# sourceMappingURL=embedding-pass.d.ts.map

package/dist/codebase-index/graph-adjacency-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Process-local cache of the wiring graph.
+ *
+ * Building the graph means pulling ~180k resolved refs, ~66k symbol→file
+ * pairs, the homonym counts and the import-visibility map, then laying the
+ * whole thing out as CSR — around half a second on this repo. That is fine
+ * once per index generation and unacceptable once per query, and the
+ * personalised retrieval walk is a per-query operation.
+ *
+ * The cache holds one graph. In the detached project server that is exactly
+ * right: one daemon serves one project. A caller for a different project (or
+ * a different index directory) simply replaces the entry rather than growing
+ * a map that would keep tens of megabytes alive for a project nobody is
+ * querying any more.
+ *
+ * Freshness is decided by the index's own `last_indexed` stamp plus the row
+ * counts, read fresh on every request. That costs three trivial queries and
+ * makes the cache self-invalidating from any path — daemon, worker, or
+ * inline — without having to be wired into the server's generation plumbing.
+ */
+import { type WiringGraph } from './graph-rank.js';
+import type { IndexStore } from './writer.js';
+/** Everything the walk needs, built together and invalidated together. */
+export interface WiringSnapshot {
+    graph: WiringGraph;
+    /** Declaring file per symbol id — the walk reports files, not just nodes. */
+    fileOf: ReadonlyMap<number, string>;
+}
+/**
+ * Return the wiring graph for this store, building it only when the index has
+ * changed since the last call.
+ */
+export declare function getWiringSnapshot(store: IndexStore, projectRoot: string, indexDir: string | undefined): WiringSnapshot;
+/** Drop the cached graph. Tests and shutdown paths only. */
+export declare function clearWiringSnapshot(): void;
+//# sourceMappingURL=graph-adjacency-cache.d.ts.map

package/dist/codebase-index/graph-rank-pass.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The index-time centrality pass.
+ *
+ * Runs inside the indexer's atomic update, immediately after ref resolution
+ * and module resolution have settled: `refs.to_id` is only final at that
+ * point, and a rank computed from half-resolved refs would describe a graph
+ * that never existed.
+ *
+ * Rank is a property of the whole graph, so this recomputes everything or
+ * nothing. That is affordable on a full run and wasteful on a one-file
+ * watcher run, which is what {@link shouldRefreshRanks} arbitrates.
+ */
+import type { IndexStore } from './writer.js';
+/**
+ * Data-version marker for the rank layer, in the same spirit as
+ * `relation_graph_version`: bumping it forces every index to recompute ranks
+ * once without a `SCHEMA_VERSION` bump (which would drop and rebuild the
+ * entire database). Older processes sharing the DB cannot downgrade it.
+ */
+export declare const RANK_VERSION = "1";
+export declare const RANK_VERSION_KEY = "rank_version";
+/**
+ * Above this many files in a targeted run, recompute. A watcher run that
+ * touches one file barely moves any score, so leaving ranks one generation
+ * stale is the cheaper trade; a bulk targeted run is effectively a full run
+ * and should not be served stale ranks.
+ */
+export declare const RANK_REFRESH_FILE_THRESHOLD = 25;
+export interface RankPassResult {
+    /** False when the pass decided the existing ranks were good enough. */
+    computed: boolean;
+    symbols: number;
+    files: number;
+    durationMs: number;
+}
+export declare function shouldRefreshRanks(store: IndexStore, opts: {
+    files?: readonly string[] | undefined;
+    force?: boolean | undefined;
+}): boolean;
+/**
+ * Recompute and persist both rank tables. Never throws: a failed rank pass
+ * leaves the previous (or empty) ranks in place and must not take the index
+ * run down with it — every consumer treats a missing rank as "unranked".
+ */
+export declare function runGraphRankPass(store: IndexStore, errors: string[]): RankPassResult;
+//# sourceMappingURL=graph-rank-pass.d.ts.map