@danypops/lector 0.1.7 → 0.1.8

package/README.md

@@ -42,6 +42,7 @@ lector workspace symbols <workspace-id> <query>
 lector workspace populate-symbol-graph <workspace-id> --max-files <n> --max-symbols-per-file <n> --background --wait-ms 500
 lector job status <job-id>
 lector workspace cache-status <workspace-id> --max-files <n> --max-symbols-per-file <n>
+lector package source <project-dir> <package-name> [--version <exact-version>] [--registry <url>] [--json]
 ```
 
 Background jobs are process-lifetime and bounded. A daemon restart or retention
@@ -49,18 +50,19 @@ expiry makes an old id unavailable; `job status` reports that explicitly. A runn
 scan returns its job id and an actionable still-loading state instead of blocking
 the caller.
 
+`package source` resolves the installed version from npm, pnpm, Yarn, or Bun lockfiles, then verifies registry repository metadata against an exact Git ref, commit, and source `package.json`. Missing, ambiguous, or mismatched source fails closed. Verified package directories are registered read-only. Private registry requests use `NPM_TOKEN`; output reports only that variable name when authentication is required.
+
 `exactEdit` requires either `--create` (the entry must not already exist) or
 `--expected-hash <hash>` (the entry must currently match that hash) — a write never
 silently overwrites content it didn't know about.
 
 ## Symbol backends
 
-Two independent `SymbolIndexPort` implementations, exercised against a shared
-conformance fixture so they're proven to agree (or documented where they don't),
-not assumed to:
+Three independent `SymbolIndexPort` implementations use one result DTO with explicit provenance and truncation:
+
+- **`typescript-language-server`** is semantic authority for identity, definitions, references, implementations, hover, diagnostics, symbols, and calls.
+- **TypeScript compiler** extracts bounded structural declarations from cold, malformed, or partially configured projects. It does not claim cross-file identity.
+- **tree-sitter** extracts bounded structural declarations and caches them by content hash. It does not claim type or language-server identity.
 
-- **`typescript-language-server`** (default) — a warm, real `tsserver` process per
-  workspace, most accurate when it has a loaded project.
-- **tree-sitter** (via `web-tree-sitter`, WASM — no native toolchain required) — no
-  subprocess, always current, results cached per file under a content-addressed key.
+Symbol results report `fidelity`, `backend`, `authority`, `freshness`, `limitations`, and `truncated`. Language-server messages, pending requests, opened files, file bytes, settling, parser files, parser nodes, parser bytes, and returned symbols are bounded.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/lector",
-	"version": "0.1.7",
+	"version": "0.1.8",
 	"description": "Platform-neutral filesystem & code-intelligence capability: core, service, and driven adapters",
 	"license": "MIT",
 	"type": "module",
@@ -18,8 +18,11 @@
 	},
 	"dependencies": {
 		"@danypops/daemon-kit": "^0.3.2",
+		"@yarnpkg/parsers": "^3.0.3",
 		"bash-language-server": "^5.6.0",
+		"fetch-retry": "^6.0.0",
 		"graphology": "^0.26.0",
+		"jsonc-parser": "^3.3.1",
 		"lru-cache": "^11.5.2",
 		"pyright": "^1.1.411",
 		"simple-git": "^3.36.0",
@@ -27,6 +30,7 @@
 		"typescript": "^5.9.3",
 		"typescript-language-server": "^5.3.0",
 		"web-tree-sitter": "0.20.8",
+		"yaml": "^2.9.0",
 		"yaml-language-server": "^1.24.0"
 	},
 	"devDependencies": {

package/src/adapters/fallback-code-intelligence-index.ts

@@ -0,0 +1,73 @@
+import type { CallHierarchyEntry, IncomingCall, OutgoingCall } from "../domain/call-hierarchy.ts";
+import type { Diagnostic } from "../domain/diagnostic.ts";
+import type { DocumentSymbolEntry } from "../domain/document-symbol.ts";
+import type { Hover } from "../domain/hover.ts";
+import type { IntelligenceProvenance, SymbolSearchBounds } from "../domain/intelligence-provenance.ts";
+import type { SymbolSearchResult, WorkspaceLocation } from "../domain/workspace-symbol.ts";
+import type { CodeIntelligencePort } from "../ports/code-intelligence-port.ts";
+import type { SymbolIndexPort } from "../ports/symbol-index-port.ts";
+
+export type ClosableIntelligenceIndex = SymbolIndexPort & { close(): Promise<void> };
+
+/** Structural fallbacks serve name discovery only; identity-aware operations always stay on the semantic primary. */
+export class FallbackCodeIntelligenceIndex implements SymbolIndexPort, CodeIntelligencePort {
+	readonly provenance: IntelligenceProvenance;
+
+	constructor(
+		private readonly primary: ClosableIntelligenceIndex & CodeIntelligencePort,
+		private readonly fallbacks: readonly ClosableIntelligenceIndex[],
+	) {
+		this.provenance = primary.provenance;
+	}
+
+	async findSymbols(query: string, bounds?: SymbolSearchBounds): Promise<SymbolSearchResult> {
+		try {
+			return await this.primary.findSymbols(query, bounds);
+		} catch (primaryError) {
+			let emptyResult: SymbolSearchResult | undefined;
+			for (const fallback of this.fallbacks) {
+				try {
+					const result = await fallback.findSymbols(query, bounds);
+					if (result.symbols.length > 0) return result;
+					emptyResult ??= result;
+				} catch {
+					// Continue through the bounded fallback chain; the primary error remains authoritative if none can answer.
+				}
+			}
+			if (emptyResult) return emptyResult;
+			throw primaryError;
+		}
+	}
+
+	goToDefinition(at: WorkspaceLocation) {
+		return this.primary.goToDefinition(at);
+	}
+	goToImplementation(at: WorkspaceLocation) {
+		return this.primary.goToImplementation(at);
+	}
+	findReferences(at: WorkspaceLocation, includeDeclaration: boolean) {
+		return this.primary.findReferences(at, includeDeclaration);
+	}
+	hover(at: WorkspaceLocation): Promise<Hover | undefined> {
+		return this.primary.hover(at);
+	}
+	documentSymbols(path: string): Promise<DocumentSymbolEntry[]> {
+		return this.primary.documentSymbols(path);
+	}
+	diagnostics(path: string): Promise<Diagnostic[]> {
+		return this.primary.diagnostics(path);
+	}
+	prepareCallHierarchy(at: WorkspaceLocation): Promise<CallHierarchyEntry[]> {
+		return this.primary.prepareCallHierarchy(at);
+	}
+	incomingCalls(at: WorkspaceLocation): Promise<IncomingCall[]> {
+		return this.primary.incomingCalls(at);
+	}
+	outgoingCalls(at: WorkspaceLocation): Promise<OutgoingCall[]> {
+		return this.primary.outgoingCalls(at);
+	}
+
+	async close(): Promise<void> {
+		await Promise.allSettled([this.primary.close(), ...this.fallbacks.map((fallback) => fallback.close())]);
+	}
+}

package/src/adapters/find-source-files.ts

@@ -17,7 +17,7 @@ export function findSourceFiles(rootPath: string, isSourceExtension: (extension:
 		} catch {
 			return;
 		}
-		for (const entry of entries) {
+		for (const entry of [...entries].sort((left, right) => left.name.localeCompare(right.name))) {
 			if (scanned >= maxFiles) return;
 			const relativePath = relativeDir ? join(relativeDir, entry.name) : entry.name;
 			if (entry.isDirectory()) {

package/src/adapters/git-repo-fetcher.ts

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 import { LRUCache } from "lru-cache";
 import simpleGit from "simple-git";
 import { assertSafeRepoReference } from "../domain/assert-safe-repo-reference.ts";
-import { RepoFetchFailed, type RepoFetchResult } from "../domain/repo-fetch-result.ts";
+import { RepoFetchCapacityExceeded, RepoFetchFailed, RepoFetchLimitExceeded, type RepoFetchPolicy, type RepoFetchResult } from "../domain/repo-fetch-result.ts";
 import type { RepoReference } from "../domain/repo-reference.ts";
 import type { RepoFetcherPort } from "../ports/repo-fetcher-port.ts";
 import { measureDirectorySizeBytes } from "./directory-size.ts";
@@ -12,12 +12,18 @@ import { measureDirectorySizeBytes } from "./directory-size.ts";
 interface RepoCacheEntry {
 	readonly path: string;
 	readonly resolvedRef: string;
+	readonly commit: string;
+	readonly cloneSizeBytes: number;
+	readonly cacheSizeBytes: number;
 	readonly fetchedAt: number;
 }
 
 const INDEX_FILENAME = "index.json";
 const DEFAULT_MAX_CACHE_BYTES = 5 * 1024 * 1024 * 1024;
 const DEFAULT_MAX_ENTRIES = 500;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_QUEUED = 32;
+const COMMIT_HASH = /^[0-9a-f]{40,64}$/i;
 
 function cacheKey(reference: RepoReference): string {
 	return `${reference.host}/${reference.owner}/${reference.repo}/${reference.ref ?? "HEAD"}`;
@@ -27,6 +33,7 @@ export interface GitRepoFetcherOptions {
 	/** Disk budget in bytes across every cached clone. Least-recently-fetched clones are deleted once exceeded. */
 	readonly maxCacheBytes?: number;
 	readonly maxEntries?: number;
+	readonly maxQueued?: number;
 	/** Maps a reference to what git should clone from. Defaults to `https://<host>/<owner>/<repo>.git`. Overridable so tests can point at a real local bare-repo fixture instead of the network. */
 	readonly resolveCloneUrl?: (reference: RepoReference) => string;
 }
@@ -35,31 +42,64 @@ function defaultCloneUrl(reference: RepoReference): string {
 	return `https://${reference.host}/${reference.owner}/${reference.repo}.git`;
 }
 
+function positiveLimit(value: number | undefined, fallback: number, field: string): number {
+	const result = value ?? fallback;
+	if (!Number.isSafeInteger(result) || result < 1) throw new TypeError(`${field} must be a positive safe integer`);
+	return result;
+}
+
+function nonNegativeLimit(value: number | undefined, fallback: number, field: string): number {
+	const result = value ?? fallback;
+	if (!Number.isSafeInteger(result) || result < 0) throw new TypeError(`${field} must be a non-negative safe integer`);
+	return result;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function validDump(value: unknown): value is Parameters<LRUCache<string, RepoCacheEntry>["load"]>[0] {
+	if (!Array.isArray(value)) return false;
+	return value.every((item) => {
+		if (!Array.isArray(item) || item.length !== 2 || typeof item[0] !== "string" || !isRecord(item[1])) return false;
+		const entry = item[1].value;
+		return (
+			isRecord(entry) &&
+			typeof entry.path === "string" &&
+			typeof entry.resolvedRef === "string" &&
+			typeof entry.commit === "string" &&
+			COMMIT_HASH.test(entry.commit) &&
+			typeof entry.cloneSizeBytes === "number" &&
+			typeof entry.cacheSizeBytes === "number" &&
+			typeof entry.fetchedAt === "number"
+		);
+	});
+}
+
 /**
- * RepoFetcherPort backed by a real `git clone --depth 1`, content-addressed by
- * (host, owner, repo, ref) under `reposDir`. Disk usage is bounded by an LRU cache keyed the same
- * way; evicting an entry deletes its directory, so the cache and the filesystem never disagree
- * about what's actually on disk. Calls are serialized through an in-process queue -- this daemon
- * is the sole writer of reposDir, so a promise chain is sufficient; no cross-process file lock
- * is needed.
+ * RepoFetcherPort backed by a real bounded `git` checkout. Calls are serialized because this
+ * daemon is the sole writer of reposDir. Exact callers never fall back to HEAD.
  */
 export class GitRepoFetcher implements RepoFetcherPort {
 	private readonly reposDir: string;
 	private readonly indexPath: string;
 	private readonly resolveCloneUrl: (reference: RepoReference) => string;
+	private readonly maxCacheBytes: number;
+	private readonly maxQueued: number;
 	private readonly cache: LRUCache<string, RepoCacheEntry>;
+	private pending = 0;
 	private queue: Promise<unknown> = Promise.resolve();
 
 	constructor(reposDir: string, options: GitRepoFetcherOptions = {}) {
 		this.reposDir = reposDir;
 		this.indexPath = join(reposDir, INDEX_FILENAME);
 		this.resolveCloneUrl = options.resolveCloneUrl ?? defaultCloneUrl;
+		this.maxCacheBytes = positiveLimit(options.maxCacheBytes, DEFAULT_MAX_CACHE_BYTES, "maxCacheBytes");
+		this.maxQueued = nonNegativeLimit(options.maxQueued, DEFAULT_MAX_QUEUED, "maxQueued");
 		this.cache = new LRUCache<string, RepoCacheEntry>({
-			maxSize: options.maxCacheBytes ?? DEFAULT_MAX_CACHE_BYTES,
-			// A single clone larger than the whole budget must still be stored (evicting everything
-			// else) rather than silently rejected -- lru-cache's own default couples this to maxSize.
+			maxSize: this.maxCacheBytes,
 			maxEntrySize: Number.MAX_SAFE_INTEGER,
-			max: options.maxEntries ?? DEFAULT_MAX_ENTRIES,
+			max: positiveLimit(options.maxEntries, DEFAULT_MAX_ENTRIES, "maxEntries"),
 			dispose: (entry) => {
 				rmSync(entry.path, { recursive: true, force: true });
 			},
@@ -67,22 +107,63 @@ export class GitRepoFetcher implements RepoFetcherPort {
 		this.loadIndex();
 	}
 
-	async fetch(reference: RepoReference): Promise<RepoFetchResult> {
+	async fetch(reference: RepoReference, policy: RepoFetchPolicy = {}): Promise<RepoFetchResult> {
 		assertSafeRepoReference(reference);
-		const task = this.queue.then(() => this.fetchLocked(reference));
+		if (this.pending > this.maxQueued) throw new RepoFetchCapacityExceeded(this.maxQueued);
+		const normalizedPolicy = {
+			exactRef: policy.exactRef ?? false,
+			maxCloneBytes: positiveLimit(policy.maxCloneBytes, Number.MAX_SAFE_INTEGER, "maxCloneBytes"),
+			maxCacheBytes: positiveLimit(policy.maxCacheBytes, this.maxCacheBytes, "maxCacheBytes"),
+			timeoutMs: positiveLimit(policy.timeoutMs, DEFAULT_TIMEOUT_MS, "timeoutMs"),
+		};
+		this.pending++;
+		const deadline = Date.now() + normalizedPolicy.timeoutMs;
+		const task = this.queue.then(() => {
+			const remaining = deadline - Date.now();
+			if (remaining <= 0) throw new RepoFetchFailed(reference.host, reference.owner, reference.repo, reference.ref, new Error("fetch timed out in queue"));
+			return this.fetchLocked(reference, { ...normalizedPolicy, timeoutMs: remaining });
+		});
 		this.queue = task.then(
 			() => undefined,
 			() => undefined,
 		);
-		return task;
+		return task.finally(() => {
+			this.pending--;
+		});
 	}
 
-	private async fetchLocked(reference: RepoReference): Promise<RepoFetchResult> {
-		const key = cacheKey(reference);
+	private trimToCacheBound(maxCacheBytes: number, requiredBytes = 0): void {
+		while (this.cache.calculatedSize + requiredBytes > maxCacheBytes && this.cache.size > 0) this.cache.pop();
+	}
+
+	private cachedResult(key: string, reference: RepoReference, policy: Required<RepoFetchPolicy>): RepoFetchResult | null {
 		const cached = this.cache.get(key);
-		if (cached) {
-			return { path: cached.path, fromCache: true, resolvedRef: cached.resolvedRef, refFallbackOccurred: false };
+		if (!cached) return null;
+		if (policy.exactRef && reference.ref !== null && cached.resolvedRef !== reference.ref) {
+			this.cache.delete(key);
+			return null;
 		}
+		if (cached.cloneSizeBytes > policy.maxCloneBytes) {
+			throw new RepoFetchLimitExceeded("clone-bytes", policy.maxCloneBytes, cached.cloneSizeBytes);
+		}
+		if (cached.cacheSizeBytes > policy.maxCacheBytes) {
+			throw new RepoFetchLimitExceeded("cache-bytes", policy.maxCacheBytes, cached.cacheSizeBytes);
+		}
+		this.trimToCacheBound(policy.maxCacheBytes);
+		if (!this.cache.has(key)) throw new RepoFetchLimitExceeded("cache-bytes", policy.maxCacheBytes, cached.cacheSizeBytes);
+		return {
+			path: cached.path,
+			fromCache: true,
+			resolvedRef: cached.resolvedRef,
+			refFallbackOccurred: false,
+			commit: cached.commit,
+		};
+	}
+
+	private async fetchLocked(reference: RepoReference, policy: Required<RepoFetchPolicy>): Promise<RepoFetchResult> {
+		const key = cacheKey(reference);
+		const cached = this.cachedResult(key, reference, policy);
+		if (cached) return cached;
 
 		const targetDir = join(this.reposDir, reference.host, reference.owner, reference.repo, reference.ref ?? "HEAD");
 		await rm(targetDir, { recursive: true, force: true });
@@ -93,47 +174,83 @@ export class GitRepoFetcher implements RepoFetcherPort {
 		let resolvedRef = reference.ref ?? "HEAD";
 		let refFallbackOccurred = false;
 		try {
-			await this.clone(url, reference.ref, tmpDir);
+			if (policy.exactRef && reference.ref !== null) {
+				await this.cloneExact(url, reference.ref, tmpDir, policy.timeoutMs);
+			} else {
+				await this.clone(url, reference.ref, tmpDir, policy.timeoutMs);
+			}
 		} catch (firstError) {
-			if (reference.ref === null) {
+			if (reference.ref === null || policy.exactRef) {
+				await rm(tmpDir, { recursive: true, force: true });
 				throw new RepoFetchFailed(reference.host, reference.owner, reference.repo, reference.ref, firstError);
 			}
 			await rm(tmpDir, { recursive: true, force: true });
 			try {
-				await this.clone(url, null, tmpDir);
+				await this.clone(url, null, tmpDir, policy.timeoutMs);
 				refFallbackOccurred = true;
 				resolvedRef = "HEAD";
 			} catch (secondError) {
+				await rm(tmpDir, { recursive: true, force: true });
 				throw new RepoFetchFailed(reference.host, reference.owner, reference.repo, reference.ref, secondError);
 			}
 		}
 
-		await rm(join(tmpDir, ".git"), { recursive: true, force: true });
-		await mkdir(dirname(targetDir), { recursive: true });
-		await rename(tmpDir, targetDir);
+		try {
+			const git = simpleGit({ baseDir: tmpDir, timeout: { block: policy.timeoutMs } });
+			const commit = (await git.revparse(["HEAD"])).trim();
+			if (!COMMIT_HASH.test(commit)) throw new Error("git returned an invalid commit id");
+			const cloneSizeBytes = await measureDirectorySizeBytes(tmpDir);
+			if (cloneSizeBytes > policy.maxCloneBytes) throw new RepoFetchLimitExceeded("clone-bytes", policy.maxCloneBytes, cloneSizeBytes);
+			await rm(join(tmpDir, ".git"), { recursive: true, force: true });
+			const cacheSizeBytes = await measureDirectorySizeBytes(tmpDir);
+			if (cacheSizeBytes > policy.maxCacheBytes) throw new RepoFetchLimitExceeded("cache-bytes", policy.maxCacheBytes, cacheSizeBytes);
+			this.trimToCacheBound(policy.maxCacheBytes, cacheSizeBytes);
+			await mkdir(dirname(targetDir), { recursive: true });
+			await rename(tmpDir, targetDir);
 
-		const sizeBytes = await measureDirectorySizeBytes(targetDir);
-		const entry: RepoCacheEntry = { path: targetDir, resolvedRef, fetchedAt: Date.now() };
-		this.cache.set(key, entry, { size: sizeBytes });
-		this.persistIndex();
+			const entry: RepoCacheEntry = { path: targetDir, resolvedRef, commit, cloneSizeBytes, cacheSizeBytes, fetchedAt: Date.now() };
+			this.cache.set(key, entry, { size: cacheSizeBytes });
+			this.persistIndex();
+			return { path: targetDir, fromCache: false, resolvedRef, refFallbackOccurred, commit };
+		} catch (error) {
+			await rm(tmpDir, { recursive: true, force: true });
+			throw error;
+		}
+	}
 
-		return { path: targetDir, fromCache: false, resolvedRef, refFallbackOccurred };
+	private async clone(url: string, ref: string | null, targetDir: string, timeoutMs: number): Promise<void> {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const options = ref ? ["--quiet", "--depth", "1", "--branch", ref] : ["--quiet", "--depth", "1"];
+			await simpleGit({ timeout: { block: timeoutMs }, abort: controller.signal }).clone(url, targetDir, options);
+		} finally {
+			clearTimeout(timer);
+		}
 	}
 
-	private async clone(url: string, ref: string | null, targetDir: string): Promise<void> {
-		const options = ref ? ["--depth", "1", "--branch", ref] : ["--depth", "1"];
-		await simpleGit().clone(url, targetDir, options);
+	private async cloneExact(url: string, ref: string, targetDir: string, timeoutMs: number): Promise<void> {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			await mkdir(targetDir, { recursive: true });
+			const git = simpleGit({ baseDir: targetDir, timeout: { block: timeoutMs }, abort: controller.signal });
+			await git.init(["--quiet"]);
+			await git.addRemote("origin", url);
+			await git.raw(["fetch", "--quiet", "--depth", "1", "origin", ref]);
+			await git.raw(["checkout", "--quiet", "--detach", "FETCH_HEAD"]);
+		} finally {
+			clearTimeout(timer);
+		}
 	}
 
 	private loadIndex(): void {
 		if (!existsSync(this.indexPath)) return;
 		try {
-			const dumped = JSON.parse(readFileSync(this.indexPath, "utf8")) as Parameters<typeof this.cache.load>[0];
-			this.cache.load(dumped);
+			const dumped: unknown = JSON.parse(readFileSync(this.indexPath, "utf8"));
+			if (validDump(dumped)) this.cache.load(dumped);
 		} catch {
-			// Corrupt or unreadable index -- start fresh, do not throw. Directories left over from a
-			// prior run are cleaned up lazily the next time their key is fetched again (fetchLocked
-			// always rm's targetDir before cloning into it).
+			// An invalid index is disposable; fetched repositories can be cloned again.
 		}
 	}
 

package/src/adapters/lsp/json-rpc-stream.ts

@@ -14,6 +14,36 @@ export interface JsonRpcMessage {
 	readonly error?: { readonly code: number; readonly message: string; readonly data?: unknown };
 }
 
+export class JsonRpcMessageLimitExceeded extends Error {
+	constructor(
+		readonly limit: "header-bytes" | "message-bytes" | "buffered-bytes",
+		readonly maxBytes: number,
+		readonly observedBytes: number,
+	) {
+		super(`JSON-RPC ${limit} exceeded ${maxBytes} bytes (observed ${observedBytes})`);
+		this.name = "JsonRpcMessageLimitExceeded";
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isJsonRpcMessage(value: unknown): value is JsonRpcMessage {
+	if (!isRecord(value) || value.jsonrpc !== "2.0") return false;
+	if (value.id !== undefined && typeof value.id !== "number" && typeof value.id !== "string") return false;
+	if (value.method !== undefined && typeof value.method !== "string") return false;
+	if (value.error !== undefined) {
+		if (!isRecord(value.error) || typeof value.error.code !== "number" || typeof value.error.message !== "string") return false;
+	}
+	return true;
+}
+
+export interface JsonRpcStreamDecoderOptions {
+	readonly maxHeaderBytes?: number;
+	readonly maxMessageBytes?: number;
+}
+
 export function encodeJsonRpcMessage(message: JsonRpcMessage): Buffer {
 	const body = Buffer.from(JSON.stringify(message), "utf-8");
 	const header = Buffer.from(`Content-Length: ${body.byteLength}\r\n\r\n`, "ascii");
@@ -28,15 +58,31 @@ export function encodeJsonRpcMessage(message: JsonRpcMessage): Buffer {
  */
 export class JsonRpcStreamDecoder {
 	private buffer: Buffer = Buffer.alloc(0);
+	private readonly maxHeaderBytes: number;
+	private readonly maxMessageBytes: number;
+
+	constructor(options: JsonRpcStreamDecoderOptions = {}) {
+		this.maxHeaderBytes = options.maxHeaderBytes ?? 8 * 1024;
+		this.maxMessageBytes = options.maxMessageBytes ?? 8 * 1024 * 1024;
+		if (!Number.isSafeInteger(this.maxHeaderBytes) || this.maxHeaderBytes < 1) throw new TypeError("maxHeaderBytes must be a positive safe integer");
+		if (!Number.isSafeInteger(this.maxMessageBytes) || this.maxMessageBytes < 1) throw new TypeError("maxMessageBytes must be a positive safe integer");
+	}
 
 	/** Feed one chunk; returns every complete message it produced (zero or more, in order). */
 	push(chunk: Buffer): JsonRpcMessage[] {
+		const bufferedBytes = this.buffer.byteLength + chunk.byteLength;
+		const maxBufferedBytes = this.maxHeaderBytes + this.maxMessageBytes;
+		if (bufferedBytes > maxBufferedBytes) throw new JsonRpcMessageLimitExceeded("buffered-bytes", maxBufferedBytes, bufferedBytes);
 		this.buffer = Buffer.concat([this.buffer, chunk]);
 		const messages: JsonRpcMessage[] = [];
 
 		for (;;) {
 			const headerEnd = this.buffer.indexOf("\r\n\r\n");
-			if (headerEnd === -1) break; // header itself split across chunks -- wait for more
+			if (headerEnd === -1) {
+				if (this.buffer.byteLength > this.maxHeaderBytes) throw new JsonRpcMessageLimitExceeded("header-bytes", this.maxHeaderBytes, this.buffer.byteLength);
+				break;
+			}
+			if (headerEnd > this.maxHeaderBytes) throw new JsonRpcMessageLimitExceeded("header-bytes", this.maxHeaderBytes, headerEnd);
 
 			const header = this.buffer.subarray(0, headerEnd).toString("ascii");
 			const match = /Content-Length:\s*(\d+)/i.exec(header);
@@ -49,6 +95,9 @@ export class JsonRpcStreamDecoder {
 			}
 
 			const length = Number.parseInt(digits, 10);
+			if (!Number.isSafeInteger(length) || length > this.maxMessageBytes) {
+				throw new JsonRpcMessageLimitExceeded("message-bytes", this.maxMessageBytes, length);
+			}
 			const bodyStart = headerEnd + 4;
 			const bodyEnd = bodyStart + length;
 			if (this.buffer.byteLength < bodyEnd) break; // body split across chunks -- wait for more
@@ -56,7 +105,8 @@ export class JsonRpcStreamDecoder {
 			const body = this.buffer.subarray(bodyStart, bodyEnd).toString("utf-8");
 			this.buffer = this.buffer.subarray(bodyEnd);
 			try {
-				messages.push(JSON.parse(body) as JsonRpcMessage);
+				const value: unknown = JSON.parse(body);
+				if (isJsonRpcMessage(value)) messages.push(value);
 			} catch {
 				// An unparseable body must not crash the whole stream -- skip it and continue.
 			}