@danypops/lector 0.1.7 → 0.1.9

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

@@ -5,9 +5,41 @@ export interface RepoFetchResult {
 	/** 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;
+	readonly commit: string;
 }
 
-/** Raised when neither the requested ref nor a default-branch fallback could be cloned. */
+export interface RepoFetchPolicy {
+	readonly exactRef?: boolean;
+	readonly maxCloneBytes?: number;
+	readonly maxCacheBytes?: number;
+	readonly timeoutMs?: number;
+}
+
+export class RepoFetchCapacityExceeded extends Error {
+	readonly maxQueued: number;
+
+	constructor(maxQueued: number) {
+		super(`repository fetch queue is full (${maxQueued} queued)`);
+		this.name = "RepoFetchCapacityExceeded";
+		this.maxQueued = maxQueued;
+	}
+}
+
+export class RepoFetchLimitExceeded extends Error {
+	readonly resource: "clone-bytes" | "cache-bytes";
+	readonly limit: number;
+	readonly observed: number;
+
+	constructor(resource: RepoFetchLimitExceeded["resource"], limit: number, observed: number) {
+		super(`repository ${resource} ${observed} exceeded limit ${limit}`);
+		this.name = "RepoFetchLimitExceeded";
+		this.resource = resource;
+		this.limit = limit;
+		this.observed = observed;
+	}
+}
+
+/** Raised when the requested ref cannot be cloned under the caller's fallback policy. */
 export class RepoFetchFailed extends Error {
 	constructor(host: string, owner: string, repo: string, ref: string | null, cause: unknown) {
 		const target = `${host}/${owner}/${repo}${ref ? `@${ref}` : ""}`;

package/src/domain/resolve-package-source.ts

@@ -0,0 +1,204 @@
+import type { PackageSourceResolverPort } from "../ports/package-source-resolver-port.ts";
+import type {
+	AmbiguousPackageSource,
+	MismatchedPackageSource,
+	OversizedPackageSource,
+	PackageSourceBounds,
+	PackageSourceOutcome,
+	PackageSourceRequest,
+	UnauthenticatedPackageSource,
+	VerifiedPackageSource,
+} from "./package-source.ts";
+
+const COMMIT_HASH = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+const CREDENTIAL_NAME = /^[A-Z][A-Z0-9_]{0,127}$/;
+const ECOSYSTEMS = ["npm", "pypi", "cargo", "go", "maven", "conan", "vcpkg", "nuget", "swiftpm"] as const;
+const VERIFICATION_METHODS = ["lockfile-vcs-pin", "registry-metadata-and-commit", "source-artifact-checksum", "local-content-digest"] as const;
+const UNAVAILABLE_CODES = [
+	"package-not-found",
+	"version-not-found",
+	"source-metadata-missing",
+	"unsupported-ecosystem",
+	"unsupported-manifest",
+	"unverifiable-source",
+] as const;
+const AMBIGUOUS_CODES = ["multiple-installed-versions", "multiple-source-candidates"] as const;
+const UNAUTHENTICATED_CODES = ["registry-authentication-required", "repository-authentication-required"] as const;
+const OVERSIZED_CODES = ["manifest-limit-exceeded", "registry-response-limit-exceeded", "clone-limit-exceeded", "cache-limit-exceeded"] as const;
+const OVERSIZED_RESOURCES = [
+	"manifest-bytes",
+	"manifest-entries",
+	"manifest-nesting",
+	"workspaces",
+	"diagnostics",
+	"registry-response-bytes",
+	"clone-bytes",
+	"cache-bytes",
+] as const;
+const MISMATCHED_CODES = ["coordinate-mismatch", "repository-ref-mismatch", "repository-commit-mismatch", "integrity-mismatch"] as const;
+
+export class InvalidPackageSourceContract extends Error {
+	constructor(reason: string) {
+		super(`invalid package-source contract: ${reason}`);
+		this.name = "InvalidPackageSourceContract";
+	}
+}
+
+function containsControlCharacter(value: string): boolean {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+
+function assertText(value: string, name: string, maxLength: number): void {
+	if (value.length === 0 || value.length > maxLength || containsControlCharacter(value)) throw new InvalidPackageSourceContract(name);
+}
+
+function assertOptionalText(value: string | null, name: string, maxLength: number): void {
+	if (value !== null) assertText(value, name, maxLength);
+}
+
+function assertAllowed(value: string, allowed: readonly string[], name: string): void {
+	if (!allowed.includes(value)) throw new InvalidPackageSourceContract(name);
+}
+
+function assertPositiveSafeInteger(value: number, name: string): void {
+	if (!Number.isSafeInteger(value) || value < 1) throw new InvalidPackageSourceContract(name);
+}
+
+function assertNonNegativeSafeInteger(value: number, name: string): void {
+	if (!Number.isSafeInteger(value) || value < 0) throw new InvalidPackageSourceContract(name);
+}
+
+function validateRequest(request: PackageSourceRequest): void {
+	assertText(request.projectRoot, "projectRoot", 4096);
+	assertAllowed(request.coordinate.ecosystem, ECOSYSTEMS, "coordinate.ecosystem");
+	assertText(request.coordinate.name, "coordinate.name", 512);
+	assertOptionalText(request.coordinate.registry, "coordinate.registry", 2048);
+	assertOptionalText(request.coordinate.requestedVersion, "coordinate.requestedVersion", 256);
+}
+
+function validateBounds(bounds: PackageSourceBounds): void {
+	assertPositiveSafeInteger(bounds.maxManifestBytes, "maxManifestBytes");
+	assertPositiveSafeInteger(bounds.maxManifestEntries, "maxManifestEntries");
+	assertPositiveSafeInteger(bounds.maxManifestNesting, "maxManifestNesting");
+	assertPositiveSafeInteger(bounds.maxWorkspaces, "maxWorkspaces");
+	assertPositiveSafeInteger(bounds.maxDiagnostics, "maxDiagnostics");
+	assertPositiveSafeInteger(bounds.maxRegistryResponseBytes, "maxRegistryResponseBytes");
+	assertNonNegativeSafeInteger(bounds.maxRedirects, "maxRedirects");
+	assertNonNegativeSafeInteger(bounds.maxRetries, "maxRetries");
+	assertPositiveSafeInteger(bounds.maxCloneBytes, "maxCloneBytes");
+	assertPositiveSafeInteger(bounds.maxCacheBytes, "maxCacheBytes");
+	assertPositiveSafeInteger(bounds.maxCandidates, "maxCandidates");
+	assertPositiveSafeInteger(bounds.timeoutMs, "timeoutMs");
+}
+
+function validateVerified(outcome: VerifiedPackageSource, request: PackageSourceRequest): void {
+	if (outcome.coordinate.ecosystem !== request.coordinate.ecosystem || outcome.coordinate.name !== request.coordinate.name) {
+		throw new InvalidPackageSourceContract("resolved coordinate differs from request");
+	}
+	if (outcome.coordinate.requestedVersion !== request.coordinate.requestedVersion || outcome.coordinate.registry !== request.coordinate.registry) {
+		throw new InvalidPackageSourceContract("resolved request identity differs from request");
+	}
+	assertText(outcome.coordinate.resolvedVersion, "coordinate.resolvedVersion", 256);
+	assertOptionalText(outcome.coordinate.registry, "coordinate.registry", 2048);
+	assertOptionalText(outcome.repository.url, "repository.url", 4096);
+	assertOptionalText(outcome.repository.requestedRef, "repository.requestedRef", 512);
+	assertOptionalText(outcome.repository.resolvedRef, "repository.resolvedRef", 512);
+	if (outcome.repository.requestedRef !== null && outcome.repository.resolvedRef !== outcome.repository.requestedRef) {
+		throw new InvalidPackageSourceContract("verified source cannot fall back from requestedRef");
+	}
+	assertAllowed(outcome.workspace.origin, ["local", "fetched"], "workspace.origin");
+	if (outcome.workspace.origin === "fetched") {
+		if (outcome.repository.commit === null || !COMMIT_HASH.test(outcome.repository.commit)) {
+			throw new InvalidPackageSourceContract("fetched source requires an exact commit");
+		}
+		if (outcome.repository.url === null || outcome.repository.resolvedRef === null) {
+			throw new InvalidPackageSourceContract("fetched source requires repository identity");
+		}
+	} else if (outcome.repository.commit !== null && !COMMIT_HASH.test(outcome.repository.commit)) {
+		throw new InvalidPackageSourceContract("repository.commit");
+	}
+	if (outcome.workspace.readOnly !== true) throw new InvalidPackageSourceContract("workspace must be read-only");
+	assertText(outcome.workspace.cachePath, "workspace.cachePath", 4096);
+	if (outcome.verification.status !== "verified") throw new InvalidPackageSourceContract("verification.status");
+	assertAllowed(outcome.verification.method, VERIFICATION_METHODS, "verification.method");
+	assertText(outcome.verification.integrity, "verification.integrity", 1024);
+}
+
+function validateAmbiguous(outcome: AmbiguousPackageSource, bounds: PackageSourceBounds): void {
+	assertAllowed(outcome.code, AMBIGUOUS_CODES, "ambiguous.code");
+	if (outcome.candidates.length === 0 || outcome.candidates.length > bounds.maxCandidates) {
+		throw new InvalidPackageSourceContract("ambiguous candidates exceed bounds");
+	}
+	for (const candidate of outcome.candidates) {
+		assertText(candidate.version, "candidate.version", 256);
+		assertText(candidate.source, "candidate.source", 4096);
+	}
+}
+
+function validateUnauthenticated(outcome: UnauthenticatedPackageSource, bounds: PackageSourceBounds): void {
+	assertAllowed(outcome.code, UNAUTHENTICATED_CODES, "unauthenticated.code");
+	if (outcome.requiredCredentialNames.length === 0 || outcome.requiredCredentialNames.length > bounds.maxCandidates) {
+		throw new InvalidPackageSourceContract("requiredCredentialNames exceed bounds");
+	}
+	for (const name of outcome.requiredCredentialNames) {
+		if (!CREDENTIAL_NAME.test(name)) throw new InvalidPackageSourceContract("credential names must be environment-variable names");
+	}
+}
+
+function validateOversized(outcome: OversizedPackageSource): void {
+	assertAllowed(outcome.code, OVERSIZED_CODES, "oversized.code");
+	assertAllowed(outcome.resource, OVERSIZED_RESOURCES, "oversized.resource");
+	assertPositiveSafeInteger(outcome.limit, "oversized.limit");
+	if (outcome.observed !== null) {
+		assertPositiveSafeInteger(outcome.observed, "oversized.observed");
+		if (outcome.observed <= outcome.limit) throw new InvalidPackageSourceContract("oversized observation does not exceed limit");
+	}
+}
+
+function validateMismatched(outcome: MismatchedPackageSource): void {
+	assertAllowed(outcome.code, MISMATCHED_CODES, "mismatched.code");
+	assertText(outcome.expected, "mismatch.expected", 4096);
+	assertText(outcome.actual, "mismatch.actual", 4096);
+	if (outcome.expected === outcome.actual) throw new InvalidPackageSourceContract("mismatch values are equal");
+}
+
+function validateOutcome(outcome: PackageSourceOutcome, request: PackageSourceRequest, bounds: PackageSourceBounds): void {
+	switch (outcome.status) {
+		case "verified":
+			validateVerified(outcome, request);
+			return;
+		case "unavailable":
+			assertAllowed(outcome.code, UNAVAILABLE_CODES, "unavailable.code");
+			return;
+		case "ambiguous":
+			validateAmbiguous(outcome, bounds);
+			return;
+		case "unauthenticated":
+			validateUnauthenticated(outcome, bounds);
+			return;
+		case "oversized":
+			validateOversized(outcome);
+			return;
+		case "mismatched":
+			validateMismatched(outcome);
+			return;
+		default:
+			throw new InvalidPackageSourceContract("outcome.status");
+	}
+}
+
+export async function resolvePackageSource(
+	resolver: PackageSourceResolverPort,
+	request: PackageSourceRequest,
+	bounds: PackageSourceBounds,
+): Promise<PackageSourceOutcome> {
+	validateRequest(request);
+	validateBounds(bounds);
+	const outcome = await resolver.resolve(request, bounds);
+	validateOutcome(outcome, request, bounds);
+	return outcome;
+}

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

@@ -1,3 +1,4 @@
+import type { IntelligenceProvenance } from "./intelligence-provenance.ts";
 import type { PopulateSymbolGraphResult } from "./populate-symbol-graph.ts";
 
 export interface SymbolGraphGeneration {
@@ -5,6 +6,10 @@ export interface SymbolGraphGeneration {
 	readonly maxFiles: number;
 	readonly maxSymbolsPerFile: number;
 	readonly completedAt: number;
+	/** Absent only for generations persisted before provenance was recorded. */
+	readonly provenance?: IntelligenceProvenance;
+	/** Per-language authorities included when provenance is polyglot. */
+	readonly sources?: readonly IntelligenceProvenance[];
 	readonly result: PopulateSymbolGraphResult;
 }
 

package/src/domain/symbol-query.ts

@@ -0,0 +1,16 @@
+export const MAX_SYMBOL_QUERY_BYTES = 4_096;
+
+export class InvalidSymbolQuery extends Error {
+	constructor(
+		readonly maxBytes: number,
+		readonly observedBytes: number,
+	) {
+		super(`symbol query exceeds ${maxBytes} UTF-8 bytes (observed ${observedBytes})`);
+		this.name = "InvalidSymbolQuery";
+	}
+}
+
+export function assertBoundedSymbolQuery(query: string): void {
+	const observedBytes = Buffer.byteLength(query, "utf-8");
+	if (observedBytes > MAX_SYMBOL_QUERY_BYTES) throw new InvalidSymbolQuery(MAX_SYMBOL_QUERY_BYTES, observedBytes);
+}

package/src/domain/workspace-symbol.ts

@@ -1,3 +1,5 @@
+import type { IntelligenceProvenance, IntelligenceSourceOutcome } from "./intelligence-provenance.ts";
+
 /** A location within a workspace file: 1-indexed line and character, matching how humans and CLIs present positions. */
 export interface WorkspaceLocation {
 	readonly path: string;
@@ -11,4 +13,15 @@ export interface WorkspaceSymbol {
 	readonly kind: string;
 	readonly location: WorkspaceLocation;
 	readonly containerName?: string;
+	/** Present when a workspace-wide composite query needs to preserve which backend produced this symbol. */
+	readonly provenance?: IntelligenceProvenance;
+}
+
+export interface SymbolSearchResult {
+	readonly symbols: readonly WorkspaceSymbol[];
+	readonly truncated: boolean;
+	readonly provenance: IntelligenceProvenance;
+	/** Present for composite workspace queries; omitted for one-language adapters. */
+	readonly completeness?: "complete" | "partial";
+	readonly sources?: readonly IntelligenceSourceOutcome[];
 }

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,26 @@ 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, LanguageFileOutsideWorkspace, 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 { PolyglotCodeIntelligenceIndex, type PolyglotIndexEntry } from "./adapters/polyglot-code-intelligence-index.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 +34,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 +81,25 @@ 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,
+	IntelligenceSourceOutcome,
+	ProvenancedResult,
+	SymbolSearchBounds,
+} from "./domain/intelligence-provenance.ts";
 export {
 	descriptorForExtension,
 	LANGUAGE_SERVER_DESCRIPTORS,
@@ -71,26 +107,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 +174,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>;
 }