@danypops/lector 0.1.6 → 0.1.8

package/src/domain/installed-package-version.ts

@@ -0,0 +1,66 @@
+export type JavaScriptPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+export interface InstalledPackageVersionRequest {
+	readonly projectRoot: string;
+	readonly packageName: string;
+	readonly requestedVersion: string | null;
+}
+
+export interface InstalledPackageVersionBounds {
+	readonly maxManifestBytes: number;
+	readonly maxManifestEntries: number;
+	readonly maxManifestNesting: number;
+	readonly maxWorkspaces: number;
+	readonly maxDiagnostics: number;
+	readonly maxCandidates: number;
+	readonly maxEvidencePerVersion: number;
+}
+
+export interface InstalledPackageEvidence {
+	readonly manager: JavaScriptPackageManager;
+	readonly lockfile: string;
+	readonly locator: string;
+	readonly integrity: string | null;
+	readonly workspace: boolean;
+}
+
+export interface ResolvedInstalledPackageVersion {
+	readonly status: "resolved";
+	readonly packageName: string;
+	readonly requestedVersion: string | null;
+	readonly version: string;
+	readonly evidence: readonly InstalledPackageEvidence[];
+	readonly evidenceTruncated: boolean;
+}
+
+export interface InstalledPackageVersionCandidate {
+	readonly version: string;
+	readonly evidence: readonly InstalledPackageEvidence[];
+	readonly evidenceTruncated: boolean;
+}
+
+export interface AmbiguousInstalledPackageVersion {
+	readonly status: "ambiguous";
+	readonly packageName: string;
+	readonly requestedVersion: null;
+	readonly candidates: readonly InstalledPackageVersionCandidate[];
+	readonly truncated: boolean;
+}
+
+export interface UnavailableInstalledPackageVersion {
+	readonly status: "unavailable";
+	readonly code: "lockfile-not-found" | "package-not-found" | "version-not-found" | "unsupported-lockfile" | "corrupt-lockfile";
+	readonly lockfile?: string;
+}
+
+export interface OversizedInstalledPackageVersion {
+	readonly status: "oversized";
+	readonly resource: "manifest-bytes" | "manifest-entries" | "manifest-nesting" | "workspaces" | "diagnostics";
+	readonly limit: number;
+}
+
+export type InstalledPackageVersionOutcome =
+	| ResolvedInstalledPackageVersion
+	| AmbiguousInstalledPackageVersion
+	| UnavailableInstalledPackageVersion
+	| OversizedInstalledPackageVersion;

package/src/domain/intelligence-provenance.ts

@@ -0,0 +1,19 @@
+export type IntelligenceFidelity = "semantic" | "structural";
+
+export interface IntelligenceProvenance {
+	readonly fidelity: IntelligenceFidelity;
+	readonly backend: string;
+	readonly languageId: string;
+	readonly authority: "language-server" | "parser" | "compiler";
+	readonly freshness: "live-process" | "content-hash" | "filesystem-snapshot";
+	readonly limitations: readonly string[];
+}
+
+export interface SymbolSearchBounds {
+	readonly maxResults: number;
+}
+
+export interface ProvenancedResult<T> {
+	readonly result: T;
+	readonly provenance: IntelligenceProvenance;
+}

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

@@ -13,7 +13,10 @@ export type LanguageServerLaunch = { readonly kind: "npm-module"; readonly entry
 
 export interface LanguageServerDescriptor {
 	readonly languageId: string;
+	readonly backendId: string;
 	readonly extensions: readonly string[];
+	/** Per-extension document language ids when one server owns a language family. */
+	readonly documentLanguageIds?: Readonly<Record<string, 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. */
@@ -30,7 +33,16 @@ export const DEFAULT_SETTLE_MS = 1000;
 
 export const TYPESCRIPT_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "typescript",
+	backendId: "typescript-language-server",
 	extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+	documentLanguageIds: {
+		".ts": "typescript",
+		".tsx": "typescriptreact",
+		".js": "javascript",
+		".jsx": "javascriptreact",
+		".mjs": "javascript",
+		".cjs": "javascript",
+	},
 	launch: { kind: "npm-module", entryModule: "typescript-language-server/lib/cli.mjs" },
 	args: ["--stdio"],
 	rootMarkers: ["tsconfig.json", "jsconfig.json", "package.json"],
@@ -43,6 +55,7 @@ export const TYPESCRIPT_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const PYTHON_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "python",
+	backendId: "pyright",
 	extensions: [".py", ".pyi"],
 	launch: { kind: "npm-module", entryModule: "pyright/langserver.index.js" },
 	args: ["--stdio"],
@@ -52,6 +65,7 @@ export const PYTHON_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const GO_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "go",
+	backendId: "gopls",
 	extensions: [".go"],
 	// gopls ships via `go install`, not npm.
 	launch: { kind: "system-binary", command: "gopls" },
@@ -62,6 +76,7 @@ export const GO_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const RUST_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "rust",
+	backendId: "rust-analyzer",
 	extensions: [".rs"],
 	// rust-analyzer ships via rustup, not npm.
 	launch: { kind: "system-binary", command: "rust-analyzer" },
@@ -73,6 +88,7 @@ export const RUST_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const CPP_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "cpp",
+	backendId: "clangd",
 	extensions: [".c", ".h", ".cc", ".cpp", ".cxx", ".hh", ".hpp", ".hxx"],
 	// clangd ships via LLVM's system packaging, not npm.
 	launch: { kind: "system-binary", command: "clangd" },
@@ -83,6 +99,7 @@ export const CPP_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const BASH_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "shellscript",
+	backendId: "bash-language-server",
 	extensions: [".sh", ".bash"],
 	launch: { kind: "npm-module", entryModule: "bash-language-server/out/cli.js" },
 	args: ["start"],
@@ -92,6 +109,7 @@ export const BASH_DESCRIPTOR: LanguageServerDescriptor = {
 
 export const YAML_DESCRIPTOR: LanguageServerDescriptor = {
 	languageId: "yaml",
+	backendId: "yaml-language-server",
 	extensions: [".yaml", ".yml"],
 	launch: { kind: "npm-module", entryModule: "yaml-language-server/bin/yaml-language-server" },
 	args: ["--stdio"],

package/src/domain/npm-package-metadata.ts

@@ -0,0 +1,26 @@
+export interface NpmRegistryVersionRequest {
+	readonly registry: string;
+	readonly name: string;
+	readonly version: string;
+}
+
+export interface NpmRegistryBounds {
+	readonly maxResponseBytes: number;
+	readonly maxRedirects: number;
+	readonly maxRetries: number;
+	readonly timeoutMs: number;
+}
+
+export interface NpmRepositoryMetadata {
+	readonly type: string | null;
+	readonly url: string;
+	readonly directory: string | null;
+}
+
+export interface NpmPackageVersionMetadata {
+	readonly name: string;
+	readonly version: string;
+	readonly repository: NpmRepositoryMetadata | null;
+	readonly gitHead: string | null;
+	readonly integrity: string | null;
+}

package/src/domain/package-source.ts

@@ -0,0 +1,143 @@
+export type PackageEcosystem = "npm" | "pypi" | "cargo" | "go" | "maven" | "conan" | "vcpkg" | "nuget" | "swiftpm";
+
+export interface PackageCoordinateRequest {
+	readonly ecosystem: PackageEcosystem;
+	readonly registry: string | null;
+	readonly name: string;
+	readonly requestedVersion: string | null;
+}
+
+export interface PackageSourceRequest {
+	readonly projectRoot: string;
+	readonly coordinate: PackageCoordinateRequest;
+}
+
+export interface PackageSourceBounds {
+	readonly maxManifestBytes: number;
+	readonly maxManifestEntries: number;
+	readonly maxManifestNesting: number;
+	readonly maxWorkspaces: number;
+	readonly maxDiagnostics: number;
+	readonly maxRegistryResponseBytes: number;
+	readonly maxRedirects: number;
+	readonly maxRetries: number;
+	readonly maxCloneBytes: number;
+	readonly maxCacheBytes: number;
+	readonly maxCandidates: number;
+	readonly timeoutMs: number;
+}
+
+export interface ResolvedPackageCoordinate extends PackageCoordinateRequest {
+	readonly resolvedVersion: string;
+}
+
+export interface PackageRepositoryIdentity {
+	readonly url: string | null;
+	readonly requestedRef: string | null;
+	readonly resolvedRef: string | null;
+	readonly commit: string | null;
+}
+
+export interface PackageSourceWorkspace {
+	readonly cachePath: string;
+	readonly origin: "local" | "fetched";
+	readonly readOnly: true;
+}
+
+export type PackageSourceVerificationMethod = "lockfile-vcs-pin" | "registry-metadata-and-commit" | "source-artifact-checksum" | "local-content-digest";
+
+export interface PackageSourceVerification {
+	readonly status: "verified";
+	readonly method: PackageSourceVerificationMethod;
+	readonly integrity: string;
+}
+
+export interface VerifiedPackageSource {
+	readonly status: "verified";
+	readonly coordinate: ResolvedPackageCoordinate;
+	readonly repository: PackageRepositoryIdentity;
+	readonly workspace: PackageSourceWorkspace;
+	readonly verification: PackageSourceVerification;
+}
+
+export type PackageSourceUnavailableCode =
+	| "package-not-found"
+	| "version-not-found"
+	| "source-metadata-missing"
+	| "unsupported-ecosystem"
+	| "unsupported-manifest"
+	| "unverifiable-source";
+
+export interface UnavailablePackageSource {
+	readonly status: "unavailable";
+	readonly code: PackageSourceUnavailableCode;
+}
+
+export interface PackageSourceCandidate {
+	readonly version: string;
+	readonly source: string;
+}
+
+export interface AmbiguousPackageSource {
+	readonly status: "ambiguous";
+	readonly code: "multiple-installed-versions" | "multiple-source-candidates";
+	readonly candidates: readonly PackageSourceCandidate[];
+	readonly truncated: boolean;
+}
+
+export interface UnauthenticatedPackageSource {
+	readonly status: "unauthenticated";
+	readonly code: "registry-authentication-required" | "repository-authentication-required";
+	readonly requiredCredentialNames: readonly string[];
+}
+
+export interface OversizedPackageSource {
+	readonly status: "oversized";
+	readonly code: "manifest-limit-exceeded" | "registry-response-limit-exceeded" | "clone-limit-exceeded" | "cache-limit-exceeded";
+	readonly resource:
+		| "manifest-bytes"
+		| "manifest-entries"
+		| "manifest-nesting"
+		| "workspaces"
+		| "diagnostics"
+		| "registry-response-bytes"
+		| "clone-bytes"
+		| "cache-bytes";
+	readonly limit: number;
+	readonly observed: number | null;
+}
+
+export interface MismatchedPackageSource {
+	readonly status: "mismatched";
+	readonly code: "coordinate-mismatch" | "repository-ref-mismatch" | "repository-commit-mismatch" | "integrity-mismatch";
+	readonly expected: string;
+	readonly actual: string;
+}
+
+export type PackageSourceOutcome =
+	| VerifiedPackageSource
+	| UnavailablePackageSource
+	| AmbiguousPackageSource
+	| UnauthenticatedPackageSource
+	| OversizedPackageSource
+	| MismatchedPackageSource;
+
+export interface PackageSourceOperationResult {
+	readonly outcome: PackageSourceOutcome;
+	readonly workspaceId: string | null;
+}
+
+export const DEFAULT_PACKAGE_SOURCE_BOUNDS: PackageSourceBounds = {
+	maxManifestBytes: 16 * 1024 * 1024,
+	maxManifestEntries: 100_000,
+	maxManifestNesting: 128,
+	maxWorkspaces: 10_000,
+	maxDiagnostics: 100,
+	maxRegistryResponseBytes: 8 * 1024 * 1024,
+	maxRedirects: 5,
+	maxRetries: 2,
+	maxCloneBytes: 512 * 1024 * 1024,
+	maxCacheBytes: 5 * 1024 * 1024 * 1024,
+	maxCandidates: 20,
+	timeoutMs: 60_000,
+};

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,8 @@ export interface SymbolGraphGeneration {
 	readonly maxFiles: number;
 	readonly maxSymbolsPerFile: number;
 	readonly completedAt: number;
+	/** Absent only for generations persisted before provenance was recorded. */
+	readonly provenance?: 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 } 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;
@@ -12,3 +14,9 @@ export interface WorkspaceSymbol {
 	readonly location: WorkspaceLocation;
 	readonly containerName?: string;
 }
+
+export interface SymbolSearchResult {
+	readonly symbols: readonly WorkspaceSymbol[];
+	readonly truncated: boolean;
+	readonly provenance: IntelligenceProvenance;
+}