@danypops/lector 0.1.0

package/src/domain/exact-edit.ts

@@ -0,0 +1,43 @@
+import type { WorkspacePort } from "../ports/workspace-port.ts";
+import type { ContentHash } from "./content-hash.ts";
+
+/**
+ * An edit intent: write `content` to `path`, guarded by the hash the caller
+ * last observed there. `expectedHash: null` asserts the path does not yet
+ * exist (a create).
+ */
+export interface ExpectedHashEdit {
+	readonly path: string;
+	readonly expectedHash: ContentHash | null;
+	readonly content: string;
+}
+
+/** The committed result of an exact edit. */
+export interface EditOutcome {
+	readonly path: string;
+	readonly previousHash: ContentHash | null;
+	readonly newHash: ContentHash;
+}
+
+/**
+ * Raised when an edit's `expectedHash` no longer matches the workspace:
+ * something else changed (or created, or removed) the entry first. The edit
+ * is rejected outright rather than silently overwriting — callers must
+ * re-observe the entry and retry with a fresh expectedHash.
+ */
+export class StaleExpectedHash extends Error {
+	constructor(
+		readonly path: string,
+		readonly expectedHash: ContentHash | null,
+		readonly actualHash: ContentHash | null,
+	) {
+		super(`stale expected hash at "${path}": expected ${expectedHash ?? "(absent)"}, found ${actualHash ?? "(absent)"}`);
+		this.name = "StaleExpectedHash";
+	}
+}
+
+/** Apply an expected-hash-guarded edit to a workspace entry. */
+export async function exactEdit(workspace: WorkspacePort, edit: ExpectedHashEdit): Promise<EditOutcome> {
+	const { previousHash, newHash } = await workspace.writeEntry(edit.path, edit.expectedHash, edit.content);
+	return { path: edit.path, previousHash, newHash };
+}

package/src/domain/find-references.ts

@@ -0,0 +1,7 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/** Every project-wide usage of the symbol at a position. */
+export async function findReferences(index: CodeIntelligencePort, at: WorkspaceLocation, includeDeclaration: boolean): Promise<WorkspaceLocation[]> {
+	return index.findReferences(at, includeDeclaration);
+}

package/src/domain/find-workspace-symbols.ts

@@ -0,0 +1,7 @@
+import type { SymbolIndexPort } from "../ports/symbol-index-port.ts";
+import type { WorkspaceSymbol } from "./workspace-symbol.ts";
+
+/** Find workspace symbols matching a fuzzy query string. */
+export async function findWorkspaceSymbols(index: SymbolIndexPort, query: string): Promise<WorkspaceSymbol[]> {
+	return index.findSymbols(query);
+}

package/src/domain/git-diff-result.ts

@@ -0,0 +1,5 @@
+/** Unified diff text, bounded per "Bound resources and outputs explicitly" -- a huge diff is truncated, never silently unbounded. */
+export interface GitDiffResult {
+	readonly diff: string;
+	readonly truncated: boolean;
+}

package/src/domain/git-log-entry.ts

@@ -0,0 +1,9 @@
+/** One commit from `git log`. */
+export interface GitLogEntry {
+	readonly sha: string;
+	readonly authorName: string;
+	readonly authorEmail: string;
+	/** ISO 8601, as git itself reports it -- never reformatted, to keep timezone info intact. */
+	readonly authoredAt: string;
+	readonly message: string;
+}

package/src/domain/git-status.ts

@@ -0,0 +1,17 @@
+/** One file's status, exposing index (staged) and working-directory (unstaged) status separately rather than a combined code -- see `git status --porcelain` for the full status-letter table. */
+export interface GitStatusEntry {
+	readonly path: string;
+	/** Present only for a rename/copy entry -- the path this one was renamed/copied from. */
+	readonly renamedFrom?: string;
+	readonly indexStatus: string;
+	readonly workingDirStatus: string;
+}
+
+/** The working tree's overall status: files plus branch tracking state. */
+export interface GitStatusSummary {
+	readonly files: readonly GitStatusEntry[];
+	readonly ahead: number;
+	readonly behind: number;
+	readonly current: string | null;
+	readonly tracking: string | null;
+}

package/src/domain/go-to-definition.ts

@@ -0,0 +1,7 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/** Where the symbol at a position is actually declared. */
+export async function goToDefinition(index: CodeIntelligencePort, at: WorkspaceLocation): Promise<WorkspaceLocation[]> {
+	return index.goToDefinition(at);
+}

package/src/domain/go-to-implementation.ts

@@ -0,0 +1,7 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/** Every concrete implementation of the interface/abstract member at a position -- crosses a port boundary that goToDefinition cannot. */
+export async function goToImplementation(index: CodeIntelligencePort, at: WorkspaceLocation): Promise<WorkspaceLocation[]> {
+	return index.goToImplementation(at);
+}

package/src/domain/hover-at.ts

@@ -0,0 +1,8 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { Hover } from "./hover.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/** Type/doc information for the symbol at a position. */
+export async function hoverAt(index: CodeIntelligencePort, at: WorkspaceLocation): Promise<Hover | undefined> {
+	return index.hover(at);
+}

package/src/domain/hover.ts

@@ -0,0 +1,7 @@
+import type { CodeRange } from "./code-range.ts";
+
+/** Type/doc information for the symbol at a position (LSP textDocument/hover, contents flattened to plain text/markdown). */
+export interface Hover {
+	readonly contents: string;
+	readonly range?: CodeRange;
+}

package/src/domain/incoming-calls.ts

@@ -0,0 +1,8 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { IncomingCall } from "./call-hierarchy.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/** Every real caller of the symbol at `at`, project-wide. */
+export async function incomingCalls(index: CodeIntelligencePort, at: WorkspaceLocation): Promise<IncomingCall[]> {
+	return index.incomingCalls(at);
+}

package/src/domain/language-server-descriptor.ts

@@ -0,0 +1,122 @@
+/**
+ * Everything needed to spawn and address one language's LSP server: how to
+ * launch it, which files it applies to, and which directory marks a real
+ * project root for it. This exact shape (command/args/extensions/root
+ * markers/extra capabilities) is independently converged on by nvim-
+ * lspconfig, mason-registry, and multiple real Pi LSP extensions
+ * (@dreki-gg/pi-lsp, @narumitw/pi-lsp, @arvoretech/pi-lsp) -- not invented
+ * here.
+ */
+
+/** An npm-module server resolves its JS entry via import.meta.resolve and runs under bun; a system-binary server (gopls, rust-analyzer, clangd) resolves by bare name against PATH. */
+export type LanguageServerLaunch = { readonly kind: "npm-module"; readonly entryModule: string } | { readonly kind: "system-binary"; readonly command: string };
+
+export interface LanguageServerDescriptor {
+	readonly languageId: string;
+	readonly extensions: readonly string[];
+	readonly launch: LanguageServerLaunch;
+	readonly args: readonly string[];
+	/** Checked nearest-first; closest match wins over a more distant one -- a monorepo subproject with its own root marker resolves to itself, not the outer repo. */
+	readonly rootMarkers: readonly string[];
+	/** Tried before the bounded directory scan when picking a file to warm the server with (e.g. a language's usual entry-point names). */
+	readonly commonSeedCandidates: readonly string[];
+	/** Extra textDocument/workspace capabilities this specific server gates real features behind (e.g. typescript-language-server withholds diagnostics/callHierarchy unless declared). */
+	readonly extraCapabilities?: Record<string, unknown>;
+	/** Milliseconds to wait after opening a file before trusting the server's answers -- no server signals "project loaded". Default 1000ms; rust-analyzer needs more (see RUST_DESCRIPTOR). */
+	readonly settleMs?: number;
+}
+
+export const DEFAULT_SETTLE_MS = 1000;
+
+export const TYPESCRIPT_DESCRIPTOR: LanguageServerDescriptor = {
+	languageId: "typescript",
+	extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+	launch: { kind: "npm-module", entryModule: "typescript-language-server/lib/cli.mjs" },
+	args: ["--stdio"],
+	rootMarkers: ["tsconfig.json", "jsconfig.json", "package.json"],
+	commonSeedCandidates: ["src/index.ts", "index.ts", "src/main.ts", "main.ts", "src/index.tsx", "index.tsx", "src/index.js", "index.js"],
+	// typescript-language-server gates its own diagnosticsSupport/callHierarchyProvider flags
+	// on these capabilities being present at all -- omitted, it silently withholds both.
+	extraCapabilities: { publishDiagnostics: {}, callHierarchy: {} },
+};
+
+export const PYTHON_DESCRIPTOR: LanguageServerDescriptor = {
+	languageId: "python",
+	extensions: [".py", ".pyi"],
+	launch: { kind: "npm-module", entryModule: "pyright/langserver.index.js" },
+	args: ["--stdio"],
+	rootMarkers: ["pyrightconfig.json", "pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile"],
+	commonSeedCandidates: ["main.py", "src/main.py", "__init__.py", "src/__init__.py"],
+};
+
+export const GO_DESCRIPTOR: LanguageServerDescriptor = {
+	languageId: "go",
+	extensions: [".go"],
+	// gopls ships via `go install`, not npm.
+	launch: { kind: "system-binary", command: "gopls" },
+	args: ["serve"],
+	rootMarkers: ["go.mod", "go.work"],
+	commonSeedCandidates: ["main.go", "cmd/main.go"],
+};
+
+export const RUST_DESCRIPTOR: LanguageServerDescriptor = {
+	languageId: "rust",
+	extensions: [".rs"],
+	// rust-analyzer ships via rustup, not npm.
+	launch: { kind: "system-binary", command: "rust-analyzer" },
+	args: [],
+	rootMarkers: ["Cargo.toml"],
+	commonSeedCandidates: ["src/main.rs", "src/lib.rs"],
+	// A query under ~800ms after didOpen can return a null result; 2500ms holds a real margin.
+	settleMs: 2500,
+};
+
+export const CPP_DESCRIPTOR: LanguageServerDescriptor = {
+	languageId: "cpp",
+	extensions: [".c", ".h", ".cc", ".cpp", ".cxx", ".hh", ".hpp", ".hxx"],
+	// clangd ships via LLVM's system packaging, not npm.
+	launch: { kind: "system-binary", command: "clangd" },
+	args: [],
+	rootMarkers: ["compile_commands.json", "compile_flags.txt", "CMakeLists.txt"],
+	commonSeedCandidates: ["main.cpp", "main.c", "src/main.cpp", "src/main.c"],
+};
+
+export const BASH_DESCRIPTOR: LanguageServerDescriptor = {
+	languageId: "shellscript",
+	extensions: [".sh", ".bash"],
+	launch: { kind: "npm-module", entryModule: "bash-language-server/out/cli.js" },
+	args: ["start"],
+	rootMarkers: [],
+	commonSeedCandidates: ["main.sh", "run.sh", "install.sh"],
+};
+
+export const YAML_DESCRIPTOR: LanguageServerDescriptor = {
+	languageId: "yaml",
+	extensions: [".yaml", ".yml"],
+	launch: { kind: "npm-module", entryModule: "yaml-language-server/bin/yaml-language-server" },
+	args: ["--stdio"],
+	rootMarkers: [],
+	commonSeedCandidates: [],
+};
+
+/** Every known descriptor, in priority order for ambiguous-extension lookups. */
+export const LANGUAGE_SERVER_DESCRIPTORS: readonly LanguageServerDescriptor[] = [
+	TYPESCRIPT_DESCRIPTOR,
+	PYTHON_DESCRIPTOR,
+	GO_DESCRIPTOR,
+	RUST_DESCRIPTOR,
+	CPP_DESCRIPTOR,
+	BASH_DESCRIPTOR,
+	YAML_DESCRIPTOR,
+];
+
+/** The first descriptor whose extensions list includes `extension` (leading dot, e.g. ".py"), or undefined if none match. */
+export function descriptorForExtension(extension: string): LanguageServerDescriptor | undefined {
+	return LANGUAGE_SERVER_DESCRIPTORS.find((descriptor) => descriptor.extensions.includes(extension));
+}
+
+/** The descriptor for a file's own extension, e.g. ".py" -> Python. */
+export function descriptorForPath(path: string): LanguageServerDescriptor | undefined {
+	const dot = path.lastIndexOf(".");
+	return dot === -1 ? undefined : descriptorForExtension(path.slice(dot));
+}

package/src/domain/outgoing-calls.ts

@@ -0,0 +1,8 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { OutgoingCall } from "./call-hierarchy.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/** Every function/method the symbol at `at` itself calls. */
+export async function outgoingCalls(index: CodeIntelligencePort, at: WorkspaceLocation): Promise<OutgoingCall[]> {
+	return index.outgoingCalls(at);
+}

package/src/domain/populate-symbol-graph.ts

@@ -0,0 +1,91 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { SymbolGraphPort, SymbolNode } from "../ports/symbol-graph-port.ts";
+import type { DocumentSymbolEntry } from "./document-symbol.ts";
+import { deriveSymbolNodeId } from "./symbol-node-id.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+const CALLABLE_KINDS = new Set(["function", "method", "constructor"]);
+
+export interface PopulateSymbolGraphResult {
+	readonly filesProcessed: number;
+	readonly symbolsProcessed: number;
+	/** addNode calls made, not necessarily new nodes -- a symbol reached from multiple edges is upserted once per encounter within a run, deduped in-memory. */
+	readonly nodesAdded: number;
+	readonly edgesAdded: number;
+}
+
+function toLocation(entry: DocumentSymbolEntry): WorkspaceLocation {
+	return { path: entry.selectionRange.path, line: entry.selectionRange.start.line, character: entry.selectionRange.start.character };
+}
+
+interface FlattenedEntry {
+	readonly entry: DocumentSymbolEntry;
+	readonly parentLocation: WorkspaceLocation | undefined;
+}
+
+/** Depth-first flatten of a documentSymbols hierarchy, keeping each entry's parent location for "contains" edges. */
+function flattenDocumentSymbols(entries: readonly DocumentSymbolEntry[], parentLocation?: WorkspaceLocation): FlattenedEntry[] {
+	const flattened: FlattenedEntry[] = [];
+	for (const entry of entries) {
+		flattened.push({ entry, parentLocation });
+		if (entry.children) flattened.push(...flattenDocumentSymbols(entry.children, toLocation(entry)));
+	}
+	return flattened;
+}
+
+/**
+ * Walks documentSymbols for each file, then outgoingCalls for every callable
+ * declaration found, to fill a SymbolGraphPort with real "contains" (free,
+ * from the hierarchy already returned) and "calls" (one LSP round trip per
+ * callable symbol) edges. maxSymbolsPerFile bounds a single large file's
+ * declarations rather than processing an unbounded number from it.
+ */
+export async function populateSymbolGraph(
+	index: CodeIntelligencePort,
+	graph: SymbolGraphPort,
+	files: readonly string[],
+	maxSymbolsPerFile: number,
+): Promise<PopulateSymbolGraphResult> {
+	let filesProcessed = 0;
+	let symbolsProcessed = 0;
+	let nodesAdded = 0;
+	let edgesAdded = 0;
+	const addedNodeIds = new Set<string>();
+
+	async function ensureNode(node: SymbolNode): Promise<void> {
+		if (addedNodeIds.has(node.id)) return;
+		addedNodeIds.add(node.id);
+		await graph.addNode(node);
+		nodesAdded++;
+	}
+
+	for (const file of files) {
+		const topLevel = await index.documentSymbols(file);
+		const flattened = flattenDocumentSymbols(topLevel).slice(0, maxSymbolsPerFile);
+		filesProcessed++;
+
+		for (const { entry, parentLocation } of flattened) {
+			symbolsProcessed++;
+			const location = toLocation(entry);
+			const node: SymbolNode = { id: deriveSymbolNodeId(location), name: entry.name, kind: entry.kind, location };
+			await ensureNode(node);
+
+			if (parentLocation) {
+				await graph.addEdge(deriveSymbolNodeId(parentLocation), node.id, "contains");
+				edgesAdded++;
+			}
+
+			if (CALLABLE_KINDS.has(entry.kind)) {
+				const callees = await index.outgoingCalls(location);
+				for (const call of callees) {
+					const calleeNode: SymbolNode = { id: deriveSymbolNodeId(call.to.location), name: call.to.name, kind: call.to.kind, location: call.to.location };
+					await ensureNode(calleeNode);
+					await graph.addEdge(node.id, calleeNode.id, "calls");
+					edgesAdded++;
+				}
+			}
+		}
+	}
+
+	return { filesProcessed, symbolsProcessed, nodesAdded, edgesAdded };
+}

package/src/domain/prepare-call-hierarchy.ts

@@ -0,0 +1,8 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { CallHierarchyEntry } from "./call-hierarchy.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/** The call-hierarchy root(s) the symbol at `at` resolves to -- usually zero or one. */
+export async function prepareCallHierarchy(index: CodeIntelligencePort, at: WorkspaceLocation): Promise<CallHierarchyEntry[]> {
+	return index.prepareCallHierarchy(at);
+}

package/src/domain/race-workspace-query.ts

@@ -0,0 +1,39 @@
+import type { WorkspaceQueryOutcome } from "./workspace-query-outcome.ts";
+
+/**
+ * Runs one workspace's query against a time budget without ever cancelling it: a timeout means
+ * this call reports "loading" and stops waiting, but the real work (e.g. LspSymbolIndex's own
+ * cached, shared initialization) keeps running in the background regardless -- a later call
+ * against the same workspace finds it already warm. Never throws: a genuine failure becomes an
+ * "error" outcome for this one workspace, not a rejection that would abort an entire fan-out.
+ */
+export function raceWorkspaceQuery<T>(
+	workspaceId: string,
+	run: () => Promise<T>,
+	timeoutMs: number,
+	loadingMessage: string,
+): Promise<WorkspaceQueryOutcome<T>> {
+	return new Promise((resolve) => {
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			resolve({ workspaceId, status: "loading", message: loadingMessage });
+		}, timeoutMs);
+
+		run().then(
+			(result) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				resolve({ workspaceId, status: "ready", result });
+			},
+			(error: unknown) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				resolve({ workspaceId, status: "error", message: error instanceof Error ? error.message : String(error) });
+			},
+		);
+	});
+}

package/src/domain/raw-read.ts

@@ -0,0 +1,24 @@
+import type { WorkspacePort } from "../ports/workspace-port.ts";
+import { type ContentHash, contentHashOf } from "./content-hash.ts";
+
+/** The result of reading a workspace entry as-is, with no structural interpretation. */
+export interface RawRead {
+	readonly path: string;
+	readonly content: string;
+	readonly hash: ContentHash;
+}
+
+/** Raised when rawRead is asked for a path the workspace does not have. */
+export class WorkspaceEntryNotFound extends Error {
+	constructor(readonly path: string) {
+		super(`no workspace entry at "${path}"`);
+		this.name = "WorkspaceEntryNotFound";
+	}
+}
+
+/** Read a workspace entry's raw content and current hash. */
+export async function rawRead(workspace: WorkspacePort, path: string): Promise<RawRead> {
+	const entry = await workspace.readEntry(path);
+	if (!entry.exists) throw new WorkspaceEntryNotFound(path);
+	return { path, content: entry.content, hash: contentHashOf(entry.content) };
+}

package/src/domain/reachable-symbols-from.ts

@@ -0,0 +1,13 @@
+import type { SymbolEdgeKind, SymbolGraphPort, SymbolNode } from "../ports/symbol-graph-port.ts";
+import type { SymbolNodeId } from "./symbol-node-id.ts";
+
+/** Every real symbol node reachable from `id`, up to `maxDepth` hops -- ids the graph itself no longer knows about (a stale node) are dropped, not fabricated. */
+export async function reachableSymbolsFrom(
+	graph: SymbolGraphPort,
+	id: SymbolNodeId,
+	options: { maxDepth: number; kind?: SymbolEdgeKind },
+): Promise<SymbolNode[]> {
+	const ids = await graph.reachableFrom(id, options);
+	const nodes = await Promise.all(ids.map((nodeId) => graph.getNode(nodeId)));
+	return nodes.filter((node): node is SymbolNode => node !== undefined);
+}

package/src/domain/repo-fetch-result.ts

@@ -0,0 +1,18 @@
+/** Result of ensuring a shallow clone exists for a RepoReference. */
+export interface RepoFetchResult {
+	readonly path: string;
+	readonly fromCache: boolean;
+	/** The ref actually checked out -- may differ from the requested ref if it didn't exist and cloning fell back to the default branch. */
+	readonly resolvedRef: string;
+	readonly refFallbackOccurred: boolean;
+}
+
+/** Raised when neither the requested ref nor a default-branch fallback could be cloned. */
+export class RepoFetchFailed extends Error {
+	constructor(host: string, owner: string, repo: string, ref: string | null, cause: unknown) {
+		const target = `${host}/${owner}/${repo}${ref ? `@${ref}` : ""}`;
+		const reason = cause instanceof Error ? cause.message : String(cause);
+		super(`failed to fetch ${target}: ${reason}`);
+		this.name = "RepoFetchFailed";
+	}
+}

package/src/domain/repo-reference.ts

@@ -0,0 +1,7 @@
+/** Identifies one external repo checkout: host/owner/repo plus an optional ref (branch/tag/sha). `ref: null` means "the remote's default branch". */
+export interface RepoReference {
+	readonly host: string;
+	readonly owner: string;
+	readonly repo: string;
+	readonly ref: string | null;
+}

package/src/domain/search-cache-key.ts

@@ -0,0 +1,16 @@
+import { createHash } from "node:crypto";
+
+/** Identifies one cached search: which workspace, what query, under what bounds. */
+export interface SearchCacheKey {
+	readonly workspaceId: string;
+	readonly query: string;
+	readonly maxMatches: number;
+	readonly maxBytes: number;
+}
+
+/** Deterministic string key for a SearchCacheKey -- same fields always yield the same key, across adapters and process restarts. */
+export function deriveSearchCacheKey(key: SearchCacheKey): string {
+	return createHash("sha256")
+		.update(JSON.stringify({ workspaceId: key.workspaceId, query: key.query, maxMatches: key.maxMatches, maxBytes: key.maxBytes }))
+		.digest("hex");
+}

package/src/domain/search-text.ts

@@ -0,0 +1,29 @@
+import type { SearchCachePort } from "../ports/search-cache-port.ts";
+import type { TextSearchOptions, TextSearchPort } from "../ports/text-search-port.ts";
+import { assertSafeSearchQuery } from "./assert-safe-search-query.ts";
+import type { TextSearchResult } from "./text-search-result.ts";
+
+/**
+ * Check-then-populate cache orchestration, kept as pure domain logic (not duplicated inside
+ * every adapter, not left for service.ts to reimplement) -- the same shape as rawRead/exactEdit
+ * being pure functions over a port. `cache` is optional: a caller with no cache configured still
+ * gets a correct (just uncached) search.
+ */
+export async function searchText(
+	textSearch: TextSearchPort,
+	cache: SearchCachePort | undefined,
+	rootPath: string,
+	workspaceId: string,
+	query: string,
+	options: TextSearchOptions,
+): Promise<TextSearchResult> {
+	assertSafeSearchQuery(query);
+	const key = { workspaceId, query, maxMatches: options.maxMatches, maxBytes: options.maxBytes };
+	if (cache) {
+		const cached = await cache.get(key);
+		if (cached) return cached;
+	}
+	const result = await textSearch.search(rootPath, query, options);
+	if (cache) await cache.set(key, result);
+	return result;
+}

package/src/domain/symbol-edges-from.ts

@@ -0,0 +1,9 @@
+import type { SymbolEdgeKind, SymbolGraphPort, SymbolNode } from "../ports/symbol-graph-port.ts";
+import type { SymbolNodeId } from "./symbol-node-id.ts";
+
+/** Every real symbol node `id` directly points to (one hop) -- ids the graph no longer knows about are dropped, not fabricated. */
+export async function symbolEdgesFrom(graph: SymbolGraphPort, id: SymbolNodeId, kind?: SymbolEdgeKind): Promise<SymbolNode[]> {
+	const ids = await graph.edgesFrom(id, kind);
+	const nodes = await Promise.all(ids.map((nodeId) => graph.getNode(nodeId)));
+	return nodes.filter((node): node is SymbolNode => node !== undefined);
+}

package/src/domain/symbol-edges-to.ts

@@ -0,0 +1,9 @@
+import type { SymbolEdgeKind, SymbolGraphPort, SymbolNode } from "../ports/symbol-graph-port.ts";
+import type { SymbolNodeId } from "./symbol-node-id.ts";
+
+/** Every real symbol node that directly points to `id` (one hop) -- ids the graph no longer knows about are dropped, not fabricated. */
+export async function symbolEdgesTo(graph: SymbolGraphPort, id: SymbolNodeId, kind?: SymbolEdgeKind): Promise<SymbolNode[]> {
+	const ids = await graph.edgesTo(id, kind);
+	const nodes = await Promise.all(ids.map((nodeId) => graph.getNode(nodeId)));
+	return nodes.filter((node): node is SymbolNode => node !== undefined);
+}

package/src/domain/symbol-graph-generation.ts

@@ -0,0 +1,14 @@
+import type { PopulateSymbolGraphResult } from "./populate-symbol-graph.ts";
+
+export interface SymbolGraphGeneration {
+	readonly sourceFingerprint: string;
+	readonly maxFiles: number;
+	readonly maxSymbolsPerFile: number;
+	readonly completedAt: number;
+	readonly result: PopulateSymbolGraphResult;
+}
+
+export type WorkspaceCacheStatus =
+	| { readonly status: "not-cached"; readonly reason: "no-completed-generation" | "bounds-changed" | "source-changed" }
+	| { readonly status: "caching"; readonly jobId: string }
+	| { readonly status: "cached"; readonly generation: SymbolGraphGeneration };

package/src/domain/symbol-node-id.ts

@@ -0,0 +1,13 @@
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/**
+ * A symbol graph node's identity: deterministic from its own declaration
+ * location, so the same declaration always maps to the same node across
+ * separate indexing passes -- never a random/incrementing id that would
+ * make two passes over the same unchanged code disagree with each other.
+ */
+export type SymbolNodeId = string;
+
+export function deriveSymbolNodeId(location: WorkspaceLocation): SymbolNodeId {
+	return `${location.path}:${location.line}:${location.character}`;
+}

package/src/domain/text-search-result.ts

@@ -0,0 +1,15 @@
+/** One matched line from a text search, with the matched span within it. */
+export interface TextSearchMatch {
+	/** Workspace-relative path. */
+	readonly path: string;
+	readonly lineNumber: number;
+	readonly line: string;
+	readonly matchStart: number;
+	readonly matchEnd: number;
+}
+
+/** `truncated` is honest, not silent: true whenever maxMatches or maxBytes cut the search short. */
+export interface TextSearchResult {
+	readonly matches: readonly TextSearchMatch[];
+	readonly truncated: boolean;
+}

package/src/domain/workspace-query-outcome.ts

@@ -0,0 +1,24 @@
+/**
+ * "ready" -- the query completed and `result` is the real answer.
+ * "loading" -- the underlying work (e.g. a cold-starting language server) hadn't finished within
+ * the caller's own budget when this was reported. This is not "not found" and not a failure: the
+ * work keeps running in the background (LspSymbolIndex's own initialization is cached and
+ * shared, never duplicated by a later call), so the caller can retry shortly and get "ready".
+ * A caller (human or agent) must be able to tell "there's nothing here" apart from "there might
+ * be something here, it just isn't ready yet" -- collapsing both into an empty result is exactly
+ * the silent-failure shape this project has repeatedly found and fixed elsewhere (pyright's
+ * workspaceFolders bug, the eslint.config.ts seed-file bug) for a single workspace; a fan-out
+ * across many workspaces multiplies the chance of hitting a still-cold one.
+ * "error" -- the query for this one workspace genuinely failed (e.g. an unsupported language).
+ * Reported per-workspace rather than aborting the whole fan-out, so one bad workspace can't sink
+ * every other workspace's real results.
+ *
+ * A real discriminated union, not one interface with optional fields -- so `status === "ready"`
+ * narrows `result` to defined without a caller needing its own assertion.
+ */
+export type WorkspaceQueryOutcome<T> =
+	| { readonly workspaceId: string; readonly status: "ready"; readonly result: T }
+	| { readonly workspaceId: string; readonly status: "loading"; readonly message: string }
+	| { readonly workspaceId: string; readonly status: "error"; readonly message: string };
+
+export type WorkspaceQueryStatus = WorkspaceQueryOutcome<unknown>["status"];

package/src/domain/workspace-symbol.ts

@@ -0,0 +1,14 @@
+/** A location within a workspace file: 1-indexed line and character, matching how humans and CLIs present positions. */
+export interface WorkspaceLocation {
+	readonly path: string;
+	readonly line: number;
+	readonly character: number;
+}
+
+/** One symbol found by a workspace-wide symbol search. */
+export interface WorkspaceSymbol {
+	readonly name: string;
+	readonly kind: string;
+	readonly location: WorkspaceLocation;
+	readonly containerName?: string;
+}