@danypops/lector 0.1.0

package/src/client.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { type DaemonPaths, readDaemonHandle } from "@danypops/daemon-kit/paths";
+import { AuthenticatedRpcClient } from "@danypops/daemon-kit/rpc-client";
+import { resolveLectorPaths } from "./constants.ts";
+import type { OperationInputs, OperationName, OperationOutputs } from "./service.ts";
+
+export type LectorClient = AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>;
+
+export interface ConnectLectorClientOptions {
+	/** Override resolved paths (tests inject an isolated tmp root). Defaults to the real XDG paths. */
+	paths?: DaemonPaths;
+}
+
+/** Connect to a running Lector daemon, probing health before returning. */
+export async function connectLectorClient(options: ConnectLectorClientOptions = {}): Promise<LectorClient> {
+	const paths = options.paths ?? resolveLectorPaths();
+	const handle = readDaemonHandle(paths.handle);
+	if (!handle) throw new Error("Lector daemon is not running; start it with `lector serve`");
+
+	let token: string;
+	try {
+		token = readFileSync(paths.token, "utf8").trim();
+	} catch {
+		throw new Error("Lector daemon token is unreadable; restart it with `lector serve`");
+	}
+
+	const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>(`http://${handle.host}:${handle.port}`, token, {
+		label: "Lector",
+	});
+	try {
+		await client.health();
+	} catch {
+		throw new Error("Lector daemon state is stale or unreachable; restart it with `lector serve`");
+	}
+	return client;
+}
+
+/**
+ * Construct a LectorClient directly against a known host/port/token, without
+ * going through paths/handle-file discovery. For callers (tests, host
+ * adapters standing up their own isolated daemon) that already have a
+ * RunningDaemon and its token in hand. Ensures every consumer of Lector's
+ * client gets the exact same AuthenticatedRpcClient class instance Lector
+ * itself depends on -- a second, independently-resolved copy of
+ * @danypops/daemon-kit in a consumer's own node_modules would otherwise be a
+ * structurally distinct (if identical-looking) type.
+ */
+export function connectLectorClientAt(baseUrl: string, token: string): LectorClient {
+	return new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>(baseUrl, token, { label: "Lector" });
+}
+
+/**
+ * True when `error` is the client-side rejection of a call whose Lector
+ * domain error was `name` (e.g. "StaleExpectedHash"). The RPC transport
+ * carries only a single error string -- see daemon.ts's ops-endpoint catch
+ * block -- so a domain error class does not survive `instanceof` across
+ * HTTP; every Lector domain error's `.name` is rendered as a `"<name>: "`
+ * prefix on that string instead, and this is the one place that convention
+ * should be read back, so host adapters never hand-roll message parsing.
+ */
+export function remoteErrorIs(error: unknown, name: string): boolean {
+	return error instanceof Error && error.message.startsWith(`${name}: `);
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+import { type DaemonPathNames, type DaemonPaths, type PathEnvironment, resolveDaemonPaths } from "@danypops/daemon-kit/paths";
+
+export const DAEMON_LABEL = "Lector";
+
+export const LECTOR_PATH_NAMES: DaemonPathNames = {
+	stateDirectoryName: "lector",
+	databaseFilename: "lector.db",
+	tokenFilename: "token",
+	handleFilename: "handle.json",
+	systemdUnitName: "lector.service",
+};
+
+/** Resolve Lector's XDG-compliant paths. Tests inject `environment` to isolate against a tmp root. */
+export function resolveLectorPaths(environment?: PathEnvironment): DaemonPaths {
+	return resolveDaemonPaths(LECTOR_PATH_NAMES, environment);
+}

package/src/daemon.ts

@@ -0,0 +1,166 @@
+import { dirname, join } from "node:path";
+import { type MaintenanceTask, type RunningDaemon, runDaemonProcess, startDaemon } from "@danypops/daemon-kit/daemon";
+import { errorResponse, healthResponse, jsonResponse, readyResponse, requireBearerToken } from "@danypops/daemon-kit/http";
+import type { Logger } from "@danypops/daemon-kit/logging";
+import { type DaemonPaths, ensureAuthToken } from "@danypops/daemon-kit/paths";
+import { GitRepoFetcher } from "./adapters/git-repo-fetcher.ts";
+import { InMemorySearchCache } from "./adapters/in-memory-search-cache.ts";
+import { SqliteSearchCache } from "./adapters/sqlite-search-cache.ts";
+import { SqliteSymbolGraph } from "./adapters/sqlite-symbol-graph.ts";
+import { TieredSearchCache } from "./adapters/tiered-search-cache.ts";
+import { resolveLectorPaths } from "./constants.ts";
+import type { RepoFetcherPort } from "./ports/repo-fetcher-port.ts";
+import type { WorkspacePort } from "./ports/workspace-port.ts";
+import { createLectorService, type LectorService, type OperationName, type WorkspaceId } from "./service.ts";
+import { lectorVersion } from "./version.ts";
+
+/** The Lector daemon's HTTP surface: Bearer-auth, health/ready, and the ops dispatch endpoint. */
+export function buildLectorApp(service: LectorService, token: string): { fetch(request: Request): Promise<Response> } {
+	return {
+		async fetch(request: Request): Promise<Response> {
+			if (!requireBearerToken(request, token)) return errorResponse("unauthorized", 401);
+			const url = new URL(request.url);
+
+			if (request.method === "GET" && url.pathname === "/health") {
+				return healthResponse(lectorVersion());
+			}
+			if (request.method === "GET" && url.pathname === "/ready") {
+				return readyResponse(true);
+			}
+			if (request.method === "GET" && url.pathname === "/api/v1/ops") {
+				return jsonResponse({ operations: service.operations });
+			}
+			if (request.method === "POST" && url.pathname === "/api/v1/ops") {
+				let body: { op?: unknown; input?: unknown };
+				try {
+					body = (await request.json()) as { op?: unknown; input?: unknown };
+				} catch {
+					return errorResponse("invalid JSON body", 400);
+				}
+				if (typeof body.op !== "string" || !service.operations.includes(body.op as OperationName)) {
+					return errorResponse(`unknown operation: ${String(body.op)}`, 400);
+				}
+				if (typeof body.input !== "object" || body.input === null) {
+					return errorResponse("input must be an object", 400);
+				}
+				try {
+					const result = await service.dispatch(body.op as OperationName, body.input as never);
+					return jsonResponse({ result });
+				} catch (error) {
+					// `toString()`, not `.message`: every Lector domain error sets a stable `.name`
+					// (StaleExpectedHash, UnknownWorkspace, ...), and Error.prototype.toString()
+					// renders it as "<name>: <message>". The RPC client's transport contract only
+					// carries a single error string, so this is the seam that lets a caller on the
+					// other side of HTTP distinguish error kinds without parsing message prose --
+					// check `error.message.startsWith("SomeDomainError: ")`, not full-message matching.
+					return errorResponse(error instanceof Error ? error.toString() : String(error), 400);
+				}
+			}
+			return errorResponse("not found", 404);
+		},
+	};
+}
+
+/**
+ * Idle-eviction TTL for warm symbol indexes (LSP subprocesses, mainly): a long-lived,
+ * dynamic-workspace daemon accumulates one per project ever queried over its uptime, with
+ * no natural point at which a project stops being relevant. 30 minutes matches Oculus's
+ * own chosen value for the identical problem (gopls warm-pool TTL eviction) -- a real,
+ * previously-shipped resource-growth fix, not an arbitrary number.
+ */
+const DEFAULT_SYMBOL_INDEX_IDLE_TTL_MS = 30 * 60 * 1000;
+const DEFAULT_SYMBOL_INDEX_REAP_INTERVAL_MS = 5 * 60 * 1000;
+
+export interface LectorDaemonOptions {
+	workspaces: ReadonlyMap<WorkspaceId, WorkspacePort>;
+	/** Override resolved paths (tests inject an isolated tmp root). Defaults to the real XDG paths. */
+	paths?: DaemonPaths;
+	logger?: Logger;
+	/** Forwarded to createLectorService -- see its own doc comment. Still refuses zero workspaces by default. */
+	allowDynamicOnly?: boolean;
+	/** Override the idle-eviction TTL for warm symbol indexes. Tests use a short value to observe eviction without waiting. */
+	symbolIndexIdleTtlMs?: number;
+	/** Override how often the idle-eviction sweep runs. */
+	symbolIndexReapIntervalMs?: number;
+	/** Override the repo.fetch backend (tests inject a GitRepoFetcher pointed at a local fixture repo, avoiding live network). Defaults to a real GitRepoFetcher under this daemon's own data directory. */
+	createRepoFetcher?: () => RepoFetcherPort;
+}
+
+function prepare(options: LectorDaemonOptions): {
+	paths: DaemonPaths;
+	app: { fetch(request: Request): Promise<Response> };
+	onShutdown: () => Promise<void>;
+	maintenanceTasks: MaintenanceTask[];
+} {
+	const paths = options.paths ?? resolveLectorPaths();
+	// One SQLite file per workspace (named by its own deterministic workspaceId) under a
+	// sibling directory of the main database -- not the same file, since SqliteSymbolGraph
+	// and any other store sharing paths.database would collide on daemon-kit's single
+	// PRAGMA user_version migration counter, silently skipping one store's own migrations.
+	const symbolGraphDirectory = join(dirname(paths.database), "symbol-graphs");
+	// One GitRepoFetcher for the whole daemon (not per-workspace, unlike symbol graphs) -- it
+	// manages its own disk-bounded LRU cache of fetched external repos under a sibling
+	// directory of the main database, independent of any single registered workspace.
+	const reposDirectory = join(dirname(paths.database), "repos");
+	// createLectorService throws synchronously on an empty registry (unless allowDynamicOnly is
+	// explicitly set), before startDaemon/runDaemonProcess ever binds a listener or writes a
+	// handle file -- the daemon fails loudly at construction rather than starting and silently
+	// returning empty/error results per call. (Locus LCS-BUG-88 class.)
+	const service = createLectorService(options.workspaces, {
+		allowDynamicOnly: options.allowDynamicOnly,
+		createSymbolGraph: (workspaceId) => new SqliteSymbolGraph(join(symbolGraphDirectory, `${workspaceId}.db`)),
+		createRepoFetcher: options.createRepoFetcher ?? (() => new GitRepoFetcher(reposDirectory)),
+		// The real production shape the SearchCachePort design was for: an in-memory tier for
+		// speed plus a disk-backed tier so repeated searches survive a daemon restart -- a single
+		// SearchCachePort adapter can only be one or the other, service.ts's own safe default is
+		// in-memory-only.
+		createSearchCache: () => new TieredSearchCache(new InMemorySearchCache(), new SqliteSearchCache(join(dirname(paths.database), "search-cache.db"))),
+	});
+	const token = ensureAuthToken(paths.token, "Lector");
+	const idleTtlMs = options.symbolIndexIdleTtlMs ?? DEFAULT_SYMBOL_INDEX_IDLE_TTL_MS;
+	// service.close() stops every warm symbol-index (LSP) subprocess the service spawned --
+	// without this hook a daemon restart would leak one language server per workspace that
+	// had ever run a symbol query. reapIdleSymbolIndexes (below) is the same idea on a timer,
+	// for indexes that go idle long before the daemon itself ever restarts.
+	return {
+		paths,
+		app: buildLectorApp(service, token),
+		onShutdown: () => service.close(),
+		maintenanceTasks: [
+			{
+				name: "reap-idle-symbol-indexes",
+				intervalMs: options.symbolIndexReapIntervalMs ?? DEFAULT_SYMBOL_INDEX_REAP_INTERVAL_MS,
+				run: async () => {
+					await service.reapIdleSymbolIndexes(idleTtlMs);
+				},
+			},
+		],
+	};
+}
+
+/** In-process entry point: no signal wiring, returns a stoppable handle. Used by tests and embedders. */
+export function startLectorDaemon(options: LectorDaemonOptions): RunningDaemon {
+	const { paths, app, onShutdown, maintenanceTasks } = prepare(options);
+	return startDaemon({
+		daemonLabel: "Lector",
+		handlePath: paths.handle,
+		buildApp: () => app,
+		logger: options.logger,
+		onShutdown,
+		maintenanceTasks,
+	});
+}
+
+/** The real binary's entry point: wires SIGINT/SIGTERM and process.exit. */
+export function serveMain(options: LectorDaemonOptions & { onListen?: (info: { host: string; port: number }) => void }): void {
+	const { paths, app, onShutdown, maintenanceTasks } = prepare(options);
+	runDaemonProcess({
+		daemonLabel: "Lector",
+		handlePath: paths.handle,
+		buildApp: () => app,
+		logger: options.logger,
+		onShutdown,
+		maintenanceTasks,
+		onListen: options.onListen,
+	});
+}

package/src/domain/assert-safe-git-argument.ts

@@ -0,0 +1,19 @@
+/** Raised when a caller-influenced string cannot safely reach git's argv. */
+export class UnsafeGitArgument extends Error {
+	constructor(readonly value: string) {
+		super(`"${value}" cannot be used as a git argument -- it would be interpreted as a flag, not a literal value`);
+		this.name = "UnsafeGitArgument";
+	}
+}
+
+/**
+ * Rejects any value git's own argv parser could interpret as a flag rather than a literal
+ * ref/path -- the root cause of most git CLI injection CVEs (simple-git's own history:
+ * `--upload-pack`, `--exec`, `--template`, `-c` config overrides all require the argument
+ * to start with `-` to be parsed as a flag at all). Lector's git layer is read-only and never
+ * needs to pass a caller-influenced flag, so this is a hard rejection, not a configurable
+ * allow-list the way simple-git's own deny-by-category defense is for a general-purpose wrapper.
+ */
+export function assertSafeGitArgument(value: string): void {
+	if (value.startsWith("-")) throw new UnsafeGitArgument(value);
+}

package/src/domain/assert-safe-path-segment.ts

@@ -0,0 +1,17 @@
+/** Raised when a caller-influenced value could escape a directory layout built by joining path segments. */
+export class UnsafePathSegment extends Error {
+	constructor(
+		readonly label: string,
+		readonly value: string,
+	) {
+		super(`"${value}" is not a safe ${label} -- must be a single non-empty path segment with no separators or ".." `);
+		this.name = "UnsafePathSegment";
+	}
+}
+
+/** Rejects empty, ".", "..", or anything containing a path separator -- the values that let a caller-influenced segment escape a directory it was meant to stay inside. */
+export function assertSafePathSegment(value: string, label: string): void {
+	if (value.length === 0 || value === "." || value === ".." || value.includes("/") || value.includes("\\")) {
+		throw new UnsafePathSegment(label, value);
+	}
+}

package/src/domain/assert-safe-repo-reference.ts

@@ -0,0 +1,20 @@
+import { assertSafeGitArgument } from "./assert-safe-git-argument.ts";
+import { assertSafePathSegment } from "./assert-safe-path-segment.ts";
+import type { RepoReference } from "./repo-reference.ts";
+
+/**
+ * Validates every caller-influenced field of a RepoReference before it reaches a git argv or a
+ * cache-directory path. host/owner/repo become single directory segments -- no separators, no
+ * "..". ref may contain "/" (branch namespacing, e.g. "feature/x") but each of its own segments
+ * still can't be "..", and the whole value can't start with "-" (git argv-flag injection).
+ */
+export function assertSafeRepoReference(reference: RepoReference): void {
+	assertSafePathSegment(reference.host, "host");
+	assertSafePathSegment(reference.owner, "owner");
+	assertSafePathSegment(reference.repo, "repo");
+	if (reference.ref === null) return;
+	assertSafeGitArgument(reference.ref);
+	for (const segment of reference.ref.split("/")) {
+		assertSafePathSegment(segment, "ref segment");
+	}
+}

package/src/domain/assert-safe-search-query.ts

@@ -0,0 +1,17 @@
+/** Raised when a caller-influenced search query could be interpreted as a ripgrep flag rather than a literal pattern. */
+export class UnsafeSearchQuery extends Error {
+	constructor(readonly value: string) {
+		super(`"${value}" cannot be used as a search query -- it would be interpreted as a flag, not a literal pattern`);
+		this.name = "UnsafeSearchQuery";
+	}
+}
+
+/**
+ * Rejects any value ripgrep's own argv parser could interpret as a flag rather than a literal
+ * pattern -- the same root cause as git's own argv-injection class, applied to a different tool.
+ * The adapter also passes `--` ahead of the query as defense in depth beyond this check, the
+ * same two-layer approach already used for git's diff ref.
+ */
+export function assertSafeSearchQuery(value: string): void {
+	if (value.startsWith("-")) throw new UnsafeSearchQuery(value);
+}

package/src/domain/bounded-job-executor.ts

@@ -0,0 +1,219 @@
+export type JobPriority = "local" | "remote";
+
+interface JobIdentity {
+	readonly id: string;
+	readonly operation: string;
+	readonly priority: JobPriority;
+	readonly submittedAt: number;
+}
+
+export type JobSnapshot<Result = unknown> =
+	| (JobIdentity & { readonly status: "queued" })
+	| (JobIdentity & { readonly status: "running"; readonly startedAt: number })
+	| (JobIdentity & { readonly status: "succeeded"; readonly startedAt: number; readonly finishedAt: number; readonly result: Result })
+	| (JobIdentity & {
+			readonly status: "failed";
+			readonly startedAt?: number;
+			readonly finishedAt: number;
+			readonly error: { readonly code: string; readonly message: string };
+	  });
+
+export class JobCapacityExceeded extends Error {
+	constructor(readonly maxQueued: number) {
+		super(`background job queue is full (${maxQueued} queued); wait for a running job to finish before submitting more work`);
+		this.name = "JobCapacityExceeded";
+	}
+}
+
+export class JobNotFound extends Error {
+	constructor(readonly jobId: string) {
+		super(`background job "${jobId}" is unknown: it expired, was evicted, or belonged to a previous daemon process`);
+		this.name = "JobNotFound";
+	}
+}
+
+export class JobExecutorClosed extends Error {
+	constructor() {
+		super("background job executor is closed");
+		this.name = "JobExecutorClosed";
+	}
+}
+
+export interface BoundedJobExecutorOptions {
+	readonly maxConcurrent: number;
+	readonly maxQueued: number;
+	readonly maxRetained: number;
+	readonly retentionMs: number;
+	readonly createId: () => string;
+	readonly now?: () => number;
+}
+
+interface JobEntry<Result> {
+	snapshot: JobSnapshot<Result>;
+	readonly run: () => Promise<Result>;
+	readonly settled: Set<() => void>;
+}
+
+const MAX_ERROR_MESSAGE_LENGTH = 1_000;
+
+/** Runs process-lifetime work with explicit concurrency, queue, retention, and priority bounds. */
+export class BoundedJobExecutor<Result = unknown> {
+	readonly #maxConcurrent: number;
+	readonly #maxQueued: number;
+	readonly #maxRetained: number;
+	readonly #retentionMs: number;
+	readonly #createId: () => string;
+	readonly #now: () => number;
+	readonly #jobs = new Map<string, JobEntry<Result>>();
+	readonly #queuedIds: string[] = [];
+	readonly #terminalIds: string[] = [];
+	#running = 0;
+	#closed = false;
+
+	constructor(options: BoundedJobExecutorOptions) {
+		for (const [name, value] of [
+			["maxConcurrent", options.maxConcurrent],
+			["maxQueued", options.maxQueued],
+			["maxRetained", options.maxRetained],
+			["retentionMs", options.retentionMs],
+		] as const) {
+			if (!Number.isSafeInteger(value) || value < (name === "maxConcurrent" ? 1 : 0)) {
+				throw new RangeError(`${name} must be a ${name === "maxConcurrent" ? "positive" : "non-negative"} safe integer`);
+			}
+		}
+		this.#maxConcurrent = options.maxConcurrent;
+		this.#maxQueued = options.maxQueued;
+		this.#maxRetained = options.maxRetained;
+		this.#retentionMs = options.retentionMs;
+		this.#createId = options.createId;
+		this.#now = options.now ?? Date.now;
+	}
+
+	submit(input: { operation: string; priority: JobPriority; run: () => Promise<Result> }): JobSnapshot<Result> {
+		if (this.#closed) throw new JobExecutorClosed();
+		this.reap();
+		if (this.#running >= this.#maxConcurrent && this.#queuedIds.length >= this.#maxQueued) {
+			throw new JobCapacityExceeded(this.#maxQueued);
+		}
+
+		const id = this.#createId();
+		if (this.#jobs.has(id)) throw new Error(`createId returned duplicate background job id "${id}"`);
+		const entry: JobEntry<Result> = {
+			snapshot: { id, operation: input.operation, priority: input.priority, submittedAt: this.#now(), status: "queued" },
+			run: input.run,
+			settled: new Set(),
+		};
+		this.#jobs.set(id, entry);
+		if (this.#running < this.#maxConcurrent) this.#start(entry);
+		else this.#queuedIds.push(id);
+		return entry.snapshot;
+	}
+
+	status(jobId: string): JobSnapshot<Result> {
+		this.reap();
+		const entry = this.#jobs.get(jobId);
+		if (!entry) throw new JobNotFound(jobId);
+		return entry.snapshot;
+	}
+
+	async wait(jobId: string, maxWaitMs: number): Promise<JobSnapshot<Result>> {
+		if (!Number.isSafeInteger(maxWaitMs) || maxWaitMs < 0) throw new RangeError("maxWaitMs must be a non-negative safe integer");
+		const entry = this.#jobs.get(jobId);
+		if (!entry) throw new JobNotFound(jobId);
+		if (entry.snapshot.status === "succeeded" || entry.snapshot.status === "failed" || maxWaitMs === 0) return entry.snapshot;
+
+		await new Promise<void>((resolve) => {
+			const settled = () => {
+				clearTimeout(timer);
+				entry.settled.delete(settled);
+				resolve();
+			};
+			entry.settled.add(settled);
+			const timer = setTimeout(settled, maxWaitMs);
+		});
+		return this.status(jobId);
+	}
+
+	reap(): number {
+		const now = this.#now();
+		let removed = 0;
+		while (this.#terminalIds.length > 0) {
+			const id = this.#terminalIds[0];
+			if (!id) break;
+			const entry = this.#jobs.get(id);
+			if (!entry || (entry.snapshot.status !== "succeeded" && entry.snapshot.status !== "failed")) {
+				this.#terminalIds.shift();
+				continue;
+			}
+			if (now - entry.snapshot.finishedAt <= this.#retentionMs) break;
+			this.#terminalIds.shift();
+			this.#jobs.delete(id);
+			removed++;
+		}
+		return removed;
+	}
+
+	close(): void {
+		this.#closed = true;
+		for (const id of this.#queuedIds.splice(0)) {
+			const entry = this.#jobs.get(id);
+			if (entry) this.#finishFailure(entry, new JobExecutorClosed());
+		}
+	}
+
+	#start(entry: JobEntry<Result>): void {
+		this.#running++;
+		entry.snapshot = { ...entry.snapshot, status: "running", startedAt: this.#now() };
+		void Promise.resolve()
+			.then(entry.run)
+			.then(
+				(result) => this.#finishSuccess(entry, result),
+				(error: unknown) => this.#finishFailure(entry, error),
+			);
+	}
+
+	#finishSuccess(entry: JobEntry<Result>, result: Result): void {
+		if (entry.snapshot.status !== "running") return;
+		entry.snapshot = { ...entry.snapshot, status: "succeeded", finishedAt: this.#now(), result };
+		this.#finish(entry);
+	}
+
+	#finishFailure(entry: JobEntry<Result>, error: unknown): void {
+		const wasRunning = entry.snapshot.status === "running";
+		const failure = error instanceof Error ? error : new Error(String(error));
+		entry.snapshot = {
+			...entry.snapshot,
+			status: "failed",
+			finishedAt: this.#now(),
+			error: { code: failure.name || "Error", message: failure.message.slice(0, MAX_ERROR_MESSAGE_LENGTH) },
+		};
+		if (wasRunning) this.#running--;
+		this.#recordTerminal(entry);
+		if (wasRunning) this.#startNext();
+	}
+
+	#finish(entry: JobEntry<Result>): void {
+		this.#running--;
+		this.#recordTerminal(entry);
+		this.#startNext();
+	}
+
+	#recordTerminal(entry: JobEntry<Result>): void {
+		this.#terminalIds.push(entry.snapshot.id);
+		for (const listener of entry.settled) listener();
+		entry.settled.clear();
+		while (this.#terminalIds.length > this.#maxRetained) {
+			const evictedId = this.#terminalIds.shift();
+			if (evictedId) this.#jobs.delete(evictedId);
+		}
+	}
+
+	#startNext(): void {
+		if (this.#closed || this.#running >= this.#maxConcurrent || this.#queuedIds.length === 0) return;
+		const localIndex = this.#queuedIds.findIndex((id) => this.#jobs.get(id)?.snapshot.priority === "local");
+		const index = localIndex >= 0 ? localIndex : 0;
+		const [nextId] = this.#queuedIds.splice(index, 1);
+		const next = nextId ? this.#jobs.get(nextId) : undefined;
+		if (next) this.#start(next);
+	}
+}

package/src/domain/call-hierarchy.ts

@@ -0,0 +1,23 @@
+import type { CodeRange } from "./code-range.ts";
+import type { WorkspaceLocation } from "./workspace-symbol.ts";
+
+/** One node in a call hierarchy: a function/method the server resolved a position to. */
+export interface CallHierarchyEntry {
+	readonly name: string;
+	readonly kind: string;
+	readonly detail?: string;
+	readonly location: WorkspaceLocation;
+	readonly range: CodeRange;
+}
+
+/** A caller of the hierarchy root, and the specific ranges within it that make the call. */
+export interface IncomingCall {
+	readonly from: CallHierarchyEntry;
+	readonly fromRanges: CodeRange[];
+}
+
+/** A callee of the hierarchy root, and the specific ranges within the root that call it. */
+export interface OutgoingCall {
+	readonly to: CallHierarchyEntry;
+	readonly fromRanges: CodeRange[];
+}

package/src/domain/code-range.ts

@@ -0,0 +1,11 @@
+/**
+ * A span within one workspace file: 1-indexed line/character, matching
+ * WorkspaceLocation's own convention (humans and CLIs present positions
+ * 1-indexed; the LSP wire format is 0-indexed -- adapters convert at the
+ * boundary, domain code never sees LSP's raw 0-indexed Range).
+ */
+export interface CodeRange {
+	readonly path: string;
+	readonly start: { readonly line: number; readonly character: number };
+	readonly end: { readonly line: number; readonly character: number };
+}

package/src/domain/content-hash.ts

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+
+/**
+ * ContentHash — an opaque fingerprint of a workspace entry's content.
+ * The domain does not care which algorithm produces it, only that two
+ * reads of unchanged content agree and any content change disagrees.
+ * Branded so a raw string can never be passed where a real hash is required.
+ */
+export type ContentHash = string & { readonly __brand: "ContentHash" };
+
+/** Compute the ContentHash for a piece of workspace entry content. */
+export function contentHashOf(content: string): ContentHash {
+	return createHash("sha256").update(content, "utf-8").digest("hex") as ContentHash;
+}

package/src/domain/diagnostic.ts

@@ -0,0 +1,12 @@
+import type { CodeRange } from "./code-range.ts";
+
+export type DiagnosticSeverity = "error" | "warning" | "information" | "hint";
+
+/** One issue a language server reports against a specific range of a file, as of its last analysis. */
+export interface Diagnostic {
+	readonly range: CodeRange;
+	readonly severity: DiagnosticSeverity;
+	readonly message: string;
+	readonly source?: string;
+	readonly code?: string | number;
+}

package/src/domain/diagnostics.ts

@@ -0,0 +1,7 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { Diagnostic } from "./diagnostic.ts";
+
+/** Every diagnostic currently known for one file (errors, warnings, and below), as of the server's last analysis. */
+export async function diagnostics(index: CodeIntelligencePort, path: string): Promise<Diagnostic[]> {
+	return index.diagnostics(path);
+}

package/src/domain/document-symbol.ts

@@ -0,0 +1,19 @@
+import type { CodeRange } from "./code-range.ts";
+
+/**
+ * A symbol declared in one specific file (LSP textDocument/documentSymbol),
+ * hierarchical -- e.g. a class's methods nest under the class -- unlike the
+ * flat, workspace-wide WorkspaceSymbol find_symbols already returns. Not
+ * every server (or backend) can honestly resolve `children`; when it can't,
+ * it is simply absent, never fabricated as an empty array.
+ */
+export interface DocumentSymbolEntry {
+	readonly name: string;
+	readonly kind: string;
+	readonly detail?: string;
+	/** Encloses the whole declaration, including its body. */
+	readonly range: CodeRange;
+	/** The narrower span that should be selected/revealed -- typically just the name. */
+	readonly selectionRange: CodeRange;
+	readonly children?: readonly DocumentSymbolEntry[];
+}

package/src/domain/document-symbols.ts

@@ -0,0 +1,7 @@
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { DocumentSymbolEntry } from "./document-symbol.ts";
+
+/** Every symbol declared in one file, hierarchically. */
+export async function documentSymbols(index: CodeIntelligencePort, path: string): Promise<DocumentSymbolEntry[]> {
+	return index.documentSymbols(path);
+}