@wrongstack/tools 1.0.0 → 1.0.2

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

@@ -0,0 +1,90 @@
+/**
+ * The Atlas brief — what an agent should already know before it asks anything.
+ *
+ * Every other part of this subsystem answers a question. This one answers the
+ * question nobody asks: *what is this repository?* An agent that has to
+ * discover the shape of an 8,000-file monorepo by search costs a dozen tool
+ * calls per session and rediscovers the same thing every session. A few
+ * hundred tokens of "here are the twenty files everything depends on, here is
+ * what each package is for" removes that repeatedly-paid cost.
+ *
+ * ## Why it is a structure, not a string
+ *
+ * The renderer lives with the caller because the budget does. The CLI's
+ * system-prompt contributor has a hard token ceiling and trims from the
+ * bottom; a webui panel or a `--brief` flag would want different cuts of the
+ * same data. Building a string here would force one budget on all of them.
+ *
+ * ## Why it reports staleness rather than hiding it
+ *
+ * A brief describing code that has since changed is worse than no brief: it
+ * is confidently wrong in a way the reader cannot detect. `staleFiles` is
+ * carried so the caller can say so out loud.
+ */
+import { type IndexStore } from './writer.js';
+/** Hubs named in the brief. Past roughly this many, it stops being a summary. */
+export declare const BRIEF_HUB_LIMIT = 20;
+/** Packages named in the brief. */
+export declare const BRIEF_PACKAGE_LIMIT = 12;
+/** Subsystem one-liners included when the concept layer has run. */
+export declare const BRIEF_SUBSYSTEM_LIMIT = 10;
+export interface AtlasBriefHub {
+    path: string;
+    /** Rank relative to the most central file in the repository. */
+    rank: number;
+    /** Concept-layer summary, when the layer has run for this file. */
+    concept?: string | undefined;
+}
+export interface AtlasBriefPackage {
+    name: string;
+    files: number;
+    /** The package's most central file. */
+    hub: string;
+}
+export interface AtlasBriefSubsystem {
+    name: string;
+    summary: string;
+}
+export interface AtlasBrief {
+    /** True once the rank pass has run; false means only counts are meaningful. */
+    ranked: boolean;
+    counts: {
+        files: number;
+        symbols: number;
+        packages: number;
+    };
+    hubs: AtlasBriefHub[];
+    packages: AtlasBriefPackage[];
+    subsystems: AtlasBriefSubsystem[];
+    /**
+     * Files whose content changed since the written atlas was generated, or
+     * `undefined` when no atlas has been written — a project that never ran
+     * `--write` is not stale, it simply has no projection.
+     */
+    staleFiles?: number | undefined;
+}
+/**
+ * Build the brief from an open store.
+ *
+ * Reads only what it names: the ranked head, not the whole ranking. On an
+ * index with no ranks this returns `ranked: false` and empty lists rather
+ * than falling back to a filename heuristic — a guess presented as the
+ * repository's structure is the failure mode this whole subsystem exists to
+ * remove.
+ */
+export declare function buildAtlasBrief(store: IndexStore, projectRoot: string): Promise<AtlasBrief>;
+/** Reported when a project has no index to summarise. */
+export type AtlasBriefIndexMissing = {
+    indexed: false;
+};
+/**
+ * Build a project's brief, owning the store lifetime.
+ *
+ * Refuses without an index for the same reason every other project-level
+ * entry point does: acquiring a store CREATES the database, and a prompt
+ * contributor must never be the thing that indexes a repository.
+ */
+export declare function buildProjectAtlasBrief(projectRoot: string, opts?: {
+    indexDir?: string | undefined;
+}): Promise<AtlasBrief | AtlasBriefIndexMissing>;
+//# sourceMappingURL=atlas-brief.d.ts.map

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

@@ -0,0 +1,38 @@
+/**
+ * Single-file, dependency-free HTML rendering of the atlas.
+ *
+ * The WebUI's CodeMap is the interactive view, but it needs a running server, a
+ * built index and a browser pointed at localhost. This is the other half: one
+ * file you can attach to a pull request, publish as a CI artifact, or mail to
+ * somebody who will never install the toolchain.
+ *
+ * ## Why it embeds rather than fetches
+ *
+ * A page that fetches `atlas.json` beside it does not work from `file://` in
+ * any modern browser — the request is a cross-origin one to a null origin. The
+ * data is inlined as JSON so a double-click opens a working map.
+ *
+ * ## Why the layout is computed here, not in the page
+ *
+ * A force simulation in the page would make the same input produce a slightly
+ * different picture on every open. Positions are computed once, deterministic
+ * given the document, so two exports of the same index are byte-identical and
+ * a committed export diffs meaningfully.
+ */
+import type { AtlasDocument } from './atlas-types.js';
+/** Packages drawn on the canvas. Beyond this the picture stops being readable. */
+export declare const EXPORT_PACKAGE_LIMIT = 40;
+/** Files listed in the ranked table. */
+export declare const EXPORT_FILE_LIMIT = 120;
+export interface AtlasExportOptions {
+    /** Repository name shown in the header. */
+    projectName?: string | undefined;
+}
+/**
+ * Render the atlas as one self-contained HTML document.
+ *
+ * Deterministic: the same {@link AtlasDocument} always produces the same bytes,
+ * with no timestamp, no random ids and no measurement of the host.
+ */
+export declare function renderAtlasHtml(document: AtlasDocument, options?: AtlasExportOptions): string;
+//# sourceMappingURL=atlas-export.d.ts.map

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

@@ -0,0 +1,114 @@
+/**
+ * Atlas — a committable projection of the codebase index.
+ *
+ * The index itself is a 180 MB SQLite database under `~/.wrongstack/projects/`:
+ * machine-local, binary, and unreviewable. That means every fresh clone, every
+ * CI run and every teammate starts cold, and nobody can see in a pull request
+ * what the index believes about the code.
+ *
+ * The atlas is the derived, human-sized answer to that: a small, deterministic
+ * set of files written into the repository at `.wrongstack/atlas/`. The
+ * database stays canonical — this is strictly a one-way projection, and
+ * regenerating it from an unchanged index must produce byte-identical output.
+ *
+ * ## Determinism is a hard requirement
+ *
+ * Anything that varies between two runs over the same index turns every
+ * indexing run into a merge conflict. So: no timestamps, no host paths, keys
+ * emitted in sorted order, floats rounded to a fixed precision, and LF line
+ * endings (the pre-commit hook enforces those repo-wide anyway).
+ *
+ * ## Staleness is reported, never guessed
+ *
+ * A committed atlas describing code that has since moved is worse than no
+ * atlas, because it is confidently wrong. {@link checkAtlasFreshness} compares
+ * the recorded per-file content hashes against the live index and says exactly
+ * which files drifted.
+ */
+import type { AtlasDocument, AtlasEdge, AtlasFile, AtlasManifest, AtlasPackage, AtlasProjection, AtlasSymbol } from './atlas-types.js';
+import type { FileRankRow } from './graph-rank.js';
+import { type IndexStore } from './writer.js';
+/** Directory the projection is written to, relative to the project root. */
+export declare const ATLAS_DIR: string;
+export declare const ATLAS_JSON = "atlas.json";
+export declare const ATLAS_MARKDOWN = "ATLAS.md";
+export declare const ATLAS_MANIFEST = "manifest.json";
+/**
+ * Bumped when the emitted shape changes. A reader seeing a different schema
+ * reports the atlas as stale rather than misinterpreting its fields.
+ */
+export declare const ATLAS_SCHEMA = 2;
+/**
+ * Files carried in the projection. Enough to describe the architecture,
+ * small enough to read in a diff — the full 8k-file list would be neither.
+ */
+export declare const ATLAS_FILE_LIMIT = 300;
+export type { AtlasDocument, AtlasEdge, AtlasFile, AtlasManifest, AtlasPackage, AtlasProjection, AtlasSymbol, };
+/**
+ * Build the projection from the index. Pure with respect to the filesystem —
+ * {@link writeAtlas} is what touches disk.
+ */
+export declare function buildAtlas(store: IndexStore, projectRoot: string): AtlasProjection;
+export interface WrittenAtlas {
+    dir: string;
+    files: string[];
+    fileCount: number;
+    packageCount: number;
+}
+/** Write the projection into `<projectRoot>/.wrongstack/atlas/`. */
+export declare function writeAtlas(store: IndexStore, projectRoot: string): Promise<WrittenAtlas>;
+export interface AtlasFreshness {
+    fresh: boolean;
+    /** Why it is not fresh. Absent when `fresh`. */
+    reason?: 'missing' | 'unreadable' | 'schema' | 'drift' | undefined;
+    /** Atlas files whose content hash no longer matches the index. */
+    changed: string[];
+    /** Atlas files the index no longer knows about. */
+    removed: string[];
+    /** Indexed files absent from the atlas manifest. */
+    added: number;
+    /** True when the whole-repository digest still matches. */
+    digestMatches: boolean;
+}
+/** Files listed in a drift report before it is summarised rather than enumerated. */
+export declare const MAX_REPORTED_DRIFT = 20;
+/**
+ * Compare the committed atlas against the live index.
+ *
+ * Reads only the manifest — the atlas document and markdown are derived from
+ * the same data, so a manifest that matches means all three are current.
+ */
+export declare function checkAtlasFreshness(store: IndexStore, projectRoot: string): Promise<AtlasFreshness>;
+/**
+ * Project-level entry points.
+ *
+ * These own the store lifetime so callers outside this package never have to
+ * touch `indexStorePool`. Both refuse to run when there is no index yet:
+ * opening a store CREATES the database, and neither writing an atlas nor
+ * checking one should be the thing that indexes a project.
+ */
+export type AtlasIndexMissing = {
+    indexed: false;
+};
+/** Write the atlas for a project, or report that it has no index yet. */
+export declare function writeProjectAtlas(projectRoot: string, opts?: {
+    indexDir?: string | undefined;
+}): Promise<WrittenAtlas | AtlasIndexMissing>;
+/** Check a project's written atlas against its index. */
+export declare function checkProjectAtlasFreshness(projectRoot: string, opts?: {
+    indexDir?: string | undefined;
+}): Promise<AtlasFreshness | AtlasIndexMissing>;
+/**
+ * Build a project's static HTML atlas, or report that it has no index yet.
+ *
+ * Returns the markup rather than writing it: where the file belongs is the
+ * caller's decision (a CI artifact directory, a temp file the CLI opens, an
+ * HTTP response body), and this package should not guess.
+ */
+export declare function exportProjectAtlasHtml(projectRoot: string, opts?: {
+    indexDir?: string | undefined;
+    projectName?: string | undefined;
+}): Promise<string | AtlasIndexMissing>;
+/** Re-exported for callers that render rank rows next to atlas output. */
+export type { FileRankRow };
+//# sourceMappingURL=atlas-projection.d.ts.map

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