@danypops/lector 0.1.6 → 0.1.8

package/src/index.ts

@@ -1,3 +1,4 @@
+export { type ClosableIntelligenceIndex, FallbackCodeIntelligenceIndex } from "./adapters/fallback-code-intelligence-index.ts";
 export { GitRepoFetcher, type GitRepoFetcherOptions } from "./adapters/git-repo-fetcher.ts";
 export { InMemoryContentCache } from "./adapters/in-memory-content-cache.ts";
 export { InMemorySearchCache, type InMemorySearchCacheOptions } from "./adapters/in-memory-search-cache.ts";
@@ -6,11 +7,25 @@ export { InMemoryWorkspace } from "./adapters/in-memory-workspace.ts";
 export { LocalFilesystemWorkspace, PathEscapesWorkspaceRoot } from "./adapters/local-filesystem-workspace.ts";
 export { LocalGit } from "./adapters/local-git.ts";
 export {
+	LanguageServerCapacityExceeded,
 	LanguageServerProcess,
 	LanguageServerProcessExited,
 	LanguageServerRequestTimedOut,
 } from "./adapters/lsp/language-server-process.ts";
-export { LspSymbolIndex } from "./adapters/lsp/lsp-symbol-index.ts";
+export { LanguageFileLimitExceeded, LspSymbolIndex, type LspSymbolIndexOptions } from "./adapters/lsp/lsp-symbol-index.ts";
+export { InvalidInstalledPackageVersionRequest, NpmLockfileVersionResolver } from "./adapters/npm-lockfile-version-resolver.ts";
+export { NpmPackageSourceResolver, type NpmPackageSourceResolverOptions } from "./adapters/npm-package-source-resolver.ts";
+export {
+	DEFAULT_NPM_REGISTRY,
+	InvalidNpmRegistryRequest,
+	NpmPackageNotFound,
+	NpmRegistryAuthenticationRequired,
+	NpmRegistryClient,
+	type NpmRegistryClientOptions,
+	NpmRegistryRequestFailed,
+	NpmRegistryResponseLimitExceeded,
+	NpmVersionNotFound,
+} from "./adapters/npm-registry-client.ts";
 export { ReadOnlyWorkspace, WorkspaceIsReadOnly } from "./adapters/read-only-workspace.ts";
 export { RipgrepTextSearch } from "./adapters/ripgrep-text-search.ts";
 export { deriveSourceManifest, type SourceManifest, SourceManifestLimitExceeded } from "./adapters/source-manifest.ts";
@@ -18,7 +33,8 @@ export { SqliteContentCache } from "./adapters/sqlite-content-cache.ts";
 export { SqliteSearchCache, type SqliteSearchCacheOptions } from "./adapters/sqlite-search-cache.ts";
 export { SqliteSymbolGraph } from "./adapters/sqlite-symbol-graph.ts";
 export { TieredSearchCache } from "./adapters/tiered-search-cache.ts";
-export { TreeSitterSymbolIndex } from "./adapters/tree-sitter/typescript-tree-sitter-symbol-index.ts";
+export { TreeSitterSymbolIndex, type TreeSitterSymbolIndexOptions } from "./adapters/tree-sitter/typescript-tree-sitter-symbol-index.ts";
+export { TypeScriptCompilerSymbolIndex, type TypeScriptCompilerSymbolIndexOptions } from "./adapters/typescript-compiler-symbol-index.ts";
 export {
 	type ConnectLectorClientOptions,
 	connectLectorClient,
@@ -64,6 +80,19 @@ export { goToImplementation } from "./domain/go-to-implementation.ts";
 export type { Hover } from "./domain/hover.ts";
 export { hoverAt } from "./domain/hover-at.ts";
 export { incomingCalls } from "./domain/incoming-calls.ts";
+export type {
+	AmbiguousInstalledPackageVersion,
+	InstalledPackageEvidence,
+	InstalledPackageVersionBounds,
+	InstalledPackageVersionCandidate,
+	InstalledPackageVersionOutcome,
+	InstalledPackageVersionRequest,
+	JavaScriptPackageManager,
+	OversizedInstalledPackageVersion,
+	ResolvedInstalledPackageVersion,
+	UnavailableInstalledPackageVersion,
+} from "./domain/installed-package-version.ts";
+export type { IntelligenceFidelity, IntelligenceProvenance, ProvenancedResult, SymbolSearchBounds } from "./domain/intelligence-provenance.ts";
 export {
 	descriptorForExtension,
 	LANGUAGE_SERVER_DESCRIPTORS,
@@ -71,26 +100,53 @@ export {
 	PYTHON_DESCRIPTOR,
 	TYPESCRIPT_DESCRIPTOR,
 } from "./domain/language-server-descriptor.ts";
+export type { NpmPackageVersionMetadata, NpmRegistryBounds, NpmRegistryVersionRequest, NpmRepositoryMetadata } from "./domain/npm-package-metadata.ts";
 export { outgoingCalls } from "./domain/outgoing-calls.ts";
+export type {
+	AmbiguousPackageSource,
+	MismatchedPackageSource,
+	OversizedPackageSource,
+	PackageCoordinateRequest,
+	PackageEcosystem,
+	PackageRepositoryIdentity,
+	PackageSourceBounds,
+	PackageSourceCandidate,
+	PackageSourceOperationResult,
+	PackageSourceOutcome,
+	PackageSourceRequest,
+	PackageSourceVerification,
+	PackageSourceVerificationMethod,
+	PackageSourceWorkspace,
+	ResolvedPackageCoordinate,
+	UnauthenticatedPackageSource,
+	UnavailablePackageSource,
+	VerifiedPackageSource,
+} from "./domain/package-source.ts";
+export { DEFAULT_PACKAGE_SOURCE_BOUNDS } from "./domain/package-source.ts";
 export { type PopulateSymbolGraphResult, populateSymbolGraph } from "./domain/populate-symbol-graph.ts";
 export { prepareCallHierarchy } from "./domain/prepare-call-hierarchy.ts";
 export { raceWorkspaceQuery } from "./domain/race-workspace-query.ts";
 export { type RawRead, rawRead, WorkspaceEntryNotFound } from "./domain/raw-read.ts";
 export { reachableSymbolsFrom } from "./domain/reachable-symbols-from.ts";
-export { RepoFetchFailed, type RepoFetchResult } from "./domain/repo-fetch-result.ts";
+export { RepoFetchCapacityExceeded, RepoFetchFailed, RepoFetchLimitExceeded, type RepoFetchPolicy, type RepoFetchResult } from "./domain/repo-fetch-result.ts";
 export type { RepoReference } from "./domain/repo-reference.ts";
+export { InvalidPackageSourceContract, resolvePackageSource } from "./domain/resolve-package-source.ts";
 export { deriveSearchCacheKey, type SearchCacheKey } from "./domain/search-cache-key.ts";
 export { searchText } from "./domain/search-text.ts";
 export { symbolEdgesFrom } from "./domain/symbol-edges-from.ts";
 export { symbolEdgesTo } from "./domain/symbol-edges-to.ts";
 export type { SymbolGraphGeneration, WorkspaceCacheStatus } from "./domain/symbol-graph-generation.ts";
 export { deriveSymbolNodeId, type SymbolNodeId } from "./domain/symbol-node-id.ts";
+export { assertBoundedSymbolQuery, InvalidSymbolQuery, MAX_SYMBOL_QUERY_BYTES } from "./domain/symbol-query.ts";
 export type { TextSearchMatch, TextSearchResult } from "./domain/text-search-result.ts";
 export type { WorkspaceQueryOutcome, WorkspaceQueryStatus } from "./domain/workspace-query-outcome.ts";
-export type { WorkspaceLocation, WorkspaceSymbol } from "./domain/workspace-symbol.ts";
+export type { SymbolSearchResult, WorkspaceLocation, WorkspaceSymbol } from "./domain/workspace-symbol.ts";
 export type { CodeIntelligencePort } from "./ports/code-intelligence-port.ts";
 export type { ContentCacheEntry, ContentCachePort, ContentSymbol } from "./ports/content-cache-port.ts";
 export type { GitPort } from "./ports/git-port.ts";
+export type { InstalledPackageVersionResolverPort } from "./ports/installed-package-version-resolver-port.ts";
+export type { NpmRegistryPort } from "./ports/npm-registry-port.ts";
+export type { PackageSourceResolverPort } from "./ports/package-source-resolver-port.ts";
 export type { RepoFetcherPort } from "./ports/repo-fetcher-port.ts";
 export type { SearchCachePort } from "./ports/search-cache-port.ts";
 export type { SymbolEdgeKind, SymbolGraphPort, SymbolNode } from "./ports/symbol-graph-port.ts";
@@ -111,6 +167,7 @@ export {
 	type OperationInputs,
 	type OperationName,
 	type OperationOutputs,
+	PackageSourceResolverNotConfigured,
 	RepoFetcherNotConfigured,
 	SymbolQueryUnavailable,
 	UnknownWorkspace,

package/src/ports/installed-package-version-resolver-port.ts

@@ -0,0 +1,5 @@
+import type { InstalledPackageVersionBounds, InstalledPackageVersionOutcome, InstalledPackageVersionRequest } from "../domain/installed-package-version.ts";
+
+export interface InstalledPackageVersionResolverPort {
+	resolve(request: InstalledPackageVersionRequest, bounds: InstalledPackageVersionBounds): Promise<InstalledPackageVersionOutcome>;
+}

package/src/ports/npm-registry-port.ts

@@ -0,0 +1,5 @@
+import type { NpmPackageVersionMetadata, NpmRegistryBounds, NpmRegistryVersionRequest } from "../domain/npm-package-metadata.ts";
+
+export interface NpmRegistryPort {
+	fetchVersion(request: NpmRegistryVersionRequest, bounds: NpmRegistryBounds): Promise<NpmPackageVersionMetadata>;
+}

package/src/ports/package-source-resolver-port.ts

@@ -0,0 +1,5 @@
+import type { PackageSourceBounds, PackageSourceOutcome, PackageSourceRequest } from "../domain/package-source.ts";
+
+export interface PackageSourceResolverPort {
+	resolve(request: PackageSourceRequest, bounds: PackageSourceBounds): Promise<PackageSourceOutcome>;
+}

package/src/ports/repo-fetcher-port.ts

@@ -1,4 +1,4 @@
-import type { RepoFetchResult } from "../domain/repo-fetch-result.ts";
+import type { RepoFetchPolicy, RepoFetchResult } from "../domain/repo-fetch-result.ts";
 import type { RepoReference } from "../domain/repo-reference.ts";
 
 /**
@@ -7,5 +7,5 @@ import type { RepoReference } from "../domain/repo-reference.ts";
  * directory to read and analyze, not one the caller owns.
  */
 export interface RepoFetcherPort {
-	fetch(reference: RepoReference): Promise<RepoFetchResult>;
+	fetch(reference: RepoReference, policy?: RepoFetchPolicy): Promise<RepoFetchResult>;
 }

package/src/ports/symbol-index-port.ts

@@ -1,4 +1,5 @@
-import type { WorkspaceSymbol } from "../domain/workspace-symbol.ts";
+import type { IntelligenceProvenance, SymbolSearchBounds } from "../domain/intelligence-provenance.ts";
+import type { SymbolSearchResult } from "../domain/workspace-symbol.ts";
 
 /**
  * SymbolIndexPort -- the role a driven adapter plays for symbol queries:
@@ -7,5 +8,6 @@ import type { WorkspaceSymbol } from "../domain/workspace-symbol.ts";
  * this same interface.
  */
 export interface SymbolIndexPort {
-	findSymbols(query: string): Promise<WorkspaceSymbol[]>;
+	readonly provenance: IntelligenceProvenance;
+	findSymbols(query: string, bounds?: SymbolSearchBounds): Promise<SymbolSearchResult>;
 }

package/src/service.ts

@@ -1,15 +1,21 @@
 import { createHash } from "node:crypto";
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
+import { FallbackCodeIntelligenceIndex } from "./adapters/fallback-code-intelligence-index.ts";
 import { InMemorySearchCache } from "./adapters/in-memory-search-cache.ts";
 import { InMemorySymbolGraph } from "./adapters/in-memory-symbol-graph.ts";
 import { LocalFilesystemWorkspace } from "./adapters/local-filesystem-workspace.ts";
 import { LocalGit } from "./adapters/local-git.ts";
 import { discoverWorkspaceDescriptor } from "./adapters/lsp/discover-seed-file.ts";
 import { LspSymbolIndex } from "./adapters/lsp/lsp-symbol-index.ts";
+import { NpmLockfileVersionResolver } from "./adapters/npm-lockfile-version-resolver.ts";
+import { NpmPackageSourceResolver } from "./adapters/npm-package-source-resolver.ts";
+import { NpmRegistryClient } from "./adapters/npm-registry-client.ts";
 import { ReadOnlyWorkspace } from "./adapters/read-only-workspace.ts";
 import { RipgrepTextSearch } from "./adapters/ripgrep-text-search.ts";
 import { deriveSourceManifest } from "./adapters/source-manifest.ts";
+import { TreeSitterSymbolIndex } from "./adapters/tree-sitter/typescript-tree-sitter-symbol-index.ts";
+import { TypeScriptCompilerSymbolIndex } from "./adapters/typescript-compiler-symbol-index.ts";
 import { BoundedJobExecutor, type JobSnapshot } from "./domain/bounded-job-executor.ts";
 import type { CallHierarchyEntry, IncomingCall, OutgoingCall } from "./domain/call-hierarchy.ts";
 import type { Diagnostic } from "./domain/diagnostic.ts";
@@ -27,8 +33,10 @@ import { goToImplementation as goToImplementationQuery } from "./domain/go-to-im
 import type { Hover } from "./domain/hover.ts";
 import { hoverAt } from "./domain/hover-at.ts";
 import { incomingCalls as incomingCallsQuery } from "./domain/incoming-calls.ts";
+import type { IntelligenceProvenance } from "./domain/intelligence-provenance.ts";
 import { descriptorForPath, LANGUAGE_SERVER_DESCRIPTORS, type LanguageServerDescriptor } from "./domain/language-server-descriptor.ts";
 import { outgoingCalls as outgoingCallsQuery } from "./domain/outgoing-calls.ts";
+import type { PackageSourceBounds, PackageSourceOperationResult, PackageSourceRequest } from "./domain/package-source.ts";
 import { type PopulateSymbolGraphResult, populateSymbolGraph as populateSymbolGraphQuery } from "./domain/populate-symbol-graph.ts";
 import { prepareCallHierarchy as prepareCallHierarchyQuery } from "./domain/prepare-call-hierarchy.ts";
 import { raceWorkspaceQuery } from "./domain/race-workspace-query.ts";
@@ -36,16 +44,19 @@ import { type RawRead, rawRead, WorkspaceEntryNotFound } from "./domain/raw-read
 import { reachableSymbolsFrom } from "./domain/reachable-symbols-from.ts";
 import type { RepoFetchResult } from "./domain/repo-fetch-result.ts";
 import type { RepoReference } from "./domain/repo-reference.ts";
+import { resolvePackageSource } from "./domain/resolve-package-source.ts";
 import { searchText as searchTextQuery } from "./domain/search-text.ts";
 import { symbolEdgesFrom } from "./domain/symbol-edges-from.ts";
 import { symbolEdgesTo } from "./domain/symbol-edges-to.ts";
 import type { WorkspaceCacheStatus } from "./domain/symbol-graph-generation.ts";
 import { deriveSymbolNodeId } from "./domain/symbol-node-id.ts";
+import { assertBoundedSymbolQuery } from "./domain/symbol-query.ts";
 import type { TextSearchResult } from "./domain/text-search-result.ts";
 import type { WorkspaceQueryOutcome } from "./domain/workspace-query-outcome.ts";
-import type { WorkspaceLocation, WorkspaceSymbol } from "./domain/workspace-symbol.ts";
+import type { SymbolSearchResult, WorkspaceLocation } from "./domain/workspace-symbol.ts";
 import type { CodeIntelligencePort } from "./ports/code-intelligence-port.ts";
 import type { GitPort } from "./ports/git-port.ts";
+import type { PackageSourceResolverPort } from "./ports/package-source-resolver-port.ts";
 import type { RepoFetcherPort } from "./ports/repo-fetcher-port.ts";
 import type { SearchCachePort } from "./ports/search-cache-port.ts";
 import type { SymbolEdgeKind, SymbolGraphPort, SymbolNode } from "./ports/symbol-graph-port.ts";
@@ -128,6 +139,13 @@ export class RepoFetcherNotConfigured extends Error {
 	}
 }
 
+export class PackageSourceResolverNotConfigured extends Error {
+	constructor() {
+		super("package.resolveSource requires a service constructed with repository fetching");
+		this.name = "PackageSourceResolverNotConfigured";
+	}
+}
+
 export class UnsupportedJobOperation extends Error {
 	constructor(readonly operation: string) {
 		super(`operation "${operation}" cannot run as a background job; supported operations: workspace.populateSymbolGraph`);
@@ -185,6 +203,7 @@ export type OperationName =
 	| "workspace.gitLog"
 	| "workspace.gitDiff"
 	| "repo.fetch"
+	| "package.resolveSource"
 	| "workspace.searchText"
 	| "search.symbols"
 	| "search.text"
@@ -215,6 +234,7 @@ export const OPERATION_NAMES: readonly OperationName[] = [
 	"workspace.gitLog",
 	"workspace.gitDiff",
 	"repo.fetch",
+	"package.resolveSource",
 	"workspace.searchText",
 	"search.symbols",
 	"search.text",
@@ -234,7 +254,7 @@ export interface OperationInputs {
 	"workspace.rawRead": { workspaceId: WorkspaceId; path: string };
 	"workspace.exactEdit": { workspaceId: WorkspaceId } & ExpectedHashEdit;
 	"workspace.registerPath": { path: string };
-	"workspace.findSymbols": { workspaceId: WorkspaceId; query: string; seedFile?: string };
+	"workspace.findSymbols": { workspaceId: WorkspaceId; query: string; seedFile?: string; maxResults?: number };
 	"workspace.goToDefinition": WorkspacePosition;
 	"workspace.goToImplementation": WorkspacePosition;
 	"workspace.findReferences": WorkspacePosition & { includeDeclaration: boolean };
@@ -254,6 +274,7 @@ export interface OperationInputs {
 	"workspace.gitLog": { workspaceId: WorkspaceId; maxCount: number };
 	"workspace.gitDiff": { workspaceId: WorkspaceId; ref?: string; maxBytes: number };
 	"repo.fetch": RepoReference;
+	"package.resolveSource": { request: PackageSourceRequest; bounds: PackageSourceBounds };
 	"workspace.searchText": { workspaceId: WorkspaceId; query: string; maxMatches: number; maxBytes: number };
 	/**
 	 * No single workspaceId -- fans out across several at once, unlike every other findSymbols-
@@ -275,20 +296,22 @@ export interface OperationInputs {
 	"job.status": { jobId: string };
 }
 
+type Provenanced<T> = T & { readonly provenance: IntelligenceProvenance };
+
 export interface OperationOutputs {
 	"workspace.rawRead": RawRead;
 	"workspace.exactEdit": EditOutcome;
 	"workspace.registerPath": { workspaceId: WorkspaceId; created: boolean };
-	"workspace.findSymbols": { symbols: readonly WorkspaceSymbol[] };
-	"workspace.goToDefinition": { locations: readonly WorkspaceLocation[] };
-	"workspace.goToImplementation": { locations: readonly WorkspaceLocation[] };
-	"workspace.findReferences": { locations: readonly WorkspaceLocation[] };
-	"workspace.hover": { hover: Hover | undefined };
-	"workspace.documentSymbols": { symbols: readonly DocumentSymbolEntry[] };
-	"workspace.diagnostics": { diagnostics: readonly Diagnostic[] };
-	"workspace.prepareCallHierarchy": { items: readonly CallHierarchyEntry[] };
-	"workspace.incomingCalls": { calls: readonly IncomingCall[] };
-	"workspace.outgoingCalls": { calls: readonly OutgoingCall[] };
+	"workspace.findSymbols": SymbolSearchResult;
+	"workspace.goToDefinition": Provenanced<{ locations: readonly WorkspaceLocation[] }>;
+	"workspace.goToImplementation": Provenanced<{ locations: readonly WorkspaceLocation[] }>;
+	"workspace.findReferences": Provenanced<{ locations: readonly WorkspaceLocation[] }>;
+	"workspace.hover": Provenanced<{ hover: Hover | undefined }>;
+	"workspace.documentSymbols": Provenanced<{ symbols: readonly DocumentSymbolEntry[] }>;
+	"workspace.diagnostics": Provenanced<{ diagnostics: readonly Diagnostic[] }>;
+	"workspace.prepareCallHierarchy": Provenanced<{ items: readonly CallHierarchyEntry[] }>;
+	"workspace.incomingCalls": Provenanced<{ calls: readonly IncomingCall[] }>;
+	"workspace.outgoingCalls": Provenanced<{ calls: readonly OutgoingCall[] }>;
 	"workspace.populateSymbolGraph": { filesProcessed: number; symbolsProcessed: number; nodesAdded: number; edgesAdded: number };
 	"workspace.reachableFrom": { symbols: readonly SymbolNode[] };
 	"workspace.symbolEdgesFrom": { symbols: readonly SymbolNode[] };
@@ -299,8 +322,9 @@ export interface OperationOutputs {
 	"workspace.gitLog": { entries: readonly GitLogEntry[] };
 	"workspace.gitDiff": GitDiffResult;
 	"repo.fetch": RepoFetchResult & { workspaceId: WorkspaceId };
+	"package.resolveSource": PackageSourceOperationResult;
 	"workspace.searchText": TextSearchResult;
-	"search.symbols": { results: readonly WorkspaceQueryOutcome<{ symbols: readonly WorkspaceSymbol[] }>[] };
+	"search.symbols": { results: readonly WorkspaceQueryOutcome<SymbolSearchResult>[] };
 	"search.text": { results: readonly WorkspaceQueryOutcome<TextSearchResult>[] };
 	"job.submit": { job: JobSnapshot<PopulateSymbolGraphResult> };
 	"job.status": { job: JobSnapshot<PopulateSymbolGraphResult> };
@@ -366,6 +390,8 @@ export interface LectorServiceOptions {
 	createGitPort?: (rootPath: string) => GitPort;
 	/** Factory for the port backing repo.fetch. No default -- unlike createSymbolGraph's safe in-memory fallback, fetching a real external repo always needs a real disk location only a host (daemon.ts) can supply. Called once at construction and reused, not per-call. */
 	createRepoFetcher?: () => RepoFetcherPort;
+	/** Override package-source resolution. With a repo fetcher configured, the default composes npm lockfiles, registry metadata, and exact Git fetching. */
+	createPackageSourceResolver?: () => PackageSourceResolverPort;
 	/** Factory for the port backing workspace.searchText. Defaults to RipgrepTextSearch -- cheap to construct, no disk dependency, safe like createGitPort's default. Called once at construction and reused. */
 	createTextSearch?: () => TextSearchPort;
 	/** Factory for workspace.searchText's result cache. Defaults to an in-memory-only InMemorySearchCache -- safe, no disk dependency. A host wanting the disk-backed tier too (surviving a restart) supplies a TieredSearchCache here. Called once at construction and reused. */
@@ -418,6 +444,7 @@ async function registerPath(registry: MutableRegistry, input: OperationInputs["w
  */
 const DEFAULT_CROSS_WORKSPACE_TIMEOUT_MS = 3000;
 const MAX_INITIAL_JOB_WAIT_MS = 30_000;
+const MAX_SYMBOL_RESULTS = 5_000;
 const MAX_SOURCE_MANIFEST_BYTES = 50 * 1024 * 1024;
 
 /**
@@ -455,7 +482,11 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	const symbolIndexes = new Map<string, { index: ClosableSymbolIndex; workspaceId: WorkspaceId; lastUsedAt: number }>();
 	const createSymbolIndex =
 		options.createSymbolIndex ??
-		((rootPath: string, descriptor: LanguageServerDescriptor, seedFile?: string) => new LspSymbolIndex(rootPath, descriptor, seedFile));
+		((rootPath: string, descriptor: LanguageServerDescriptor, seedFile?: string) => {
+			const semantic = new LspSymbolIndex(rootPath, descriptor, seedFile);
+			if (descriptor.languageId !== "typescript") return semantic;
+			return new FallbackCodeIntelligenceIndex(semantic, [new TypeScriptCompilerSymbolIndex(rootPath), new TreeSitterSymbolIndex(rootPath)]);
+		});
 	function symbolIndexKey(workspaceId: WorkspaceId, languageId: string): string {
 		return `${workspaceId}:${languageId}`;
 	}
@@ -481,6 +512,11 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	// every time, wastefully, and would risk losing the in-memory LRU's recency ordering
 	// between calls for no benefit (the index itself is what makes rehydration correct at all).
 	const repoFetcher = options.createRepoFetcher?.();
+	const packageSourceResolver =
+		options.createPackageSourceResolver?.() ??
+		(repoFetcher
+			? new NpmPackageSourceResolver({ versions: new NpmLockfileVersionResolver(), registry: new NpmRegistryClient(), repositories: repoFetcher })
+			: undefined);
 	const textSearch = options.createTextSearch?.() ?? new RipgrepTextSearch();
 	const searchCache = options.createSearchCache?.() ?? new InMemorySearchCache();
 
@@ -521,6 +557,28 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 		return { workspaceId, ...result };
 	}
 
+	async function packageSourceHandler(
+		registry: MutableRegistry,
+		input: OperationInputs["package.resolveSource"],
+	): Promise<OperationOutputs["package.resolveSource"]> {
+		if (!packageSourceResolver) throw new PackageSourceResolverNotConfigured();
+		const outcome = await resolvePackageSource(packageSourceResolver, input.request, input.bounds);
+		if (outcome.status !== "verified") return { outcome, workspaceId: null };
+		const absolutePath = resolve(outcome.workspace.cachePath);
+		let sourceStats: Awaited<ReturnType<typeof stat>>;
+		try {
+			sourceStats = await stat(absolutePath);
+		} catch {
+			throw new InvalidWorkspaceRoot(absolutePath, "verified package source does not exist or is not accessible");
+		}
+		if (!sourceStats.isDirectory()) throw new InvalidWorkspaceRoot(absolutePath, "verified package source is not a directory");
+		const workspaceId = deriveWorkspaceId(absolutePath);
+		if (!registry.has(workspaceId)) {
+			registry.set(workspaceId, { port: new ReadOnlyWorkspace(new LocalFilesystemWorkspace(absolutePath)), rootPath: absolutePath, origin: "remote" });
+		}
+		return { outcome, workspaceId };
+	}
+
 	async function searchTextHandler(
 		registry: MutableRegistry,
 		input: OperationInputs["workspace.searchText"],
@@ -660,9 +718,13 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	}
 
 	async function findSymbols(_registry: MutableRegistry, input: OperationInputs["workspace.findSymbols"]): Promise<OperationOutputs["workspace.findSymbols"]> {
+		assertBoundedSymbolQuery(input.query);
+		const maxResults = input.maxResults ?? 1_000;
+		if (!Number.isSafeInteger(maxResults) || maxResults < 1 || maxResults > MAX_SYMBOL_RESULTS) {
+			throw new TypeError(`maxResults must be a positive safe integer no greater than ${MAX_SYMBOL_RESULTS}`);
+		}
 		const { index } = await ensureWarmIndex(input);
-		const symbols = await findWorkspaceSymbols(index, input.query);
-		return { symbols };
+		return findWorkspaceSymbols(index, input.query, { maxResults });
 	}
 
 	async function requireCodeIntelligence(input: {
@@ -681,7 +743,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	): Promise<OperationOutputs["workspace.goToDefinition"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const locations = await goToDefinitionQuery(index, { path: input.path, line: input.line, character: input.character });
-		return { locations };
+		return { locations, provenance: index.provenance };
 	}
 
 	async function goToImplementation(
@@ -690,7 +752,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	): Promise<OperationOutputs["workspace.goToImplementation"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const locations = await goToImplementationQuery(index, { path: input.path, line: input.line, character: input.character });
-		return { locations };
+		return { locations, provenance: index.provenance };
 	}
 
 	async function findReferences(
@@ -699,13 +761,13 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	): Promise<OperationOutputs["workspace.findReferences"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const locations = await findReferencesQuery(index, { path: input.path, line: input.line, character: input.character }, input.includeDeclaration);
-		return { locations };
+		return { locations, provenance: index.provenance };
 	}
 
 	async function hover(_registry: MutableRegistry, input: OperationInputs["workspace.hover"]): Promise<OperationOutputs["workspace.hover"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const hover = await hoverAt(index, { path: input.path, line: input.line, character: input.character });
-		return { hover };
+		return { hover, provenance: index.provenance };
 	}
 
 	async function documentSymbolsHandler(
@@ -714,7 +776,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	): Promise<OperationOutputs["workspace.documentSymbols"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const symbols = await documentSymbolsQuery(index, input.path);
-		return { symbols };
+		return { symbols, provenance: index.provenance };
 	}
 
 	async function diagnosticsHandler(
@@ -723,7 +785,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	): Promise<OperationOutputs["workspace.diagnostics"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const diagnostics = await diagnosticsQuery(index, input.path);
-		return { diagnostics };
+		return { diagnostics, provenance: index.provenance };
 	}
 
 	async function prepareCallHierarchyHandler(
@@ -732,7 +794,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	): Promise<OperationOutputs["workspace.prepareCallHierarchy"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const items = await prepareCallHierarchyQuery(index, { path: input.path, line: input.line, character: input.character });
-		return { items };
+		return { items, provenance: index.provenance };
 	}
 
 	async function incomingCallsHandler(
@@ -741,7 +803,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	): Promise<OperationOutputs["workspace.incomingCalls"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const calls = await incomingCallsQuery(index, { path: input.path, line: input.line, character: input.character });
-		return { calls };
+		return { calls, provenance: index.provenance };
 	}
 
 	async function outgoingCallsHandler(
@@ -750,7 +812,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 	): Promise<OperationOutputs["workspace.outgoingCalls"]> {
 		const { index } = await requireCodeIntelligence(input);
 		const calls = await outgoingCallsQuery(index, { path: input.path, line: input.line, character: input.character });
-		return { calls };
+		return { calls, provenance: index.provenance };
 	}
 
 	async function populateSymbolGraphHandler(
@@ -771,6 +833,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 			maxFiles: input.maxFiles,
 			maxSymbolsPerFile: input.maxSymbolsPerFile,
 			completedAt: Date.now(),
+			provenance: index.provenance,
 			result,
 		});
 		return result;
@@ -920,6 +983,7 @@ export function createLectorService(workspaces: ReadonlyMap<WorkspaceId, Workspa
 		"workspace.gitLog": gitLogHandler,
 		"workspace.gitDiff": gitDiffHandler,
 		"repo.fetch": repoFetchHandler,
+		"package.resolveSource": packageSourceHandler,
 		"workspace.searchText": searchTextHandler,
 		"search.symbols": crossFindSymbols,
 		"search.text": crossSearchText,