@khanhicetea/pi-better-tool 0.2.1 → 0.2.3

package/src/read-symbol.ts

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+import { boundCompleteOutput, fenceFor } from "./diagnostics.ts";
+import { resolveToolPath } from "./paths.ts";
+import { readSource, sourceReadError } from "./source-file.ts";
+import { indexSymbols, languageForPath, SUPPORTED_LANGUAGES, type SourceSymbol } from "./symbols.ts";
+import { getLineSpans } from "./text.ts";
+
+export const readSymbolSchema = Type.Object({
+	path: Type.String({ minLength: 1, maxLength: 4096, description: "Local source file path (relative, absolute, @path, ~/path, or file URL)." }),
+	line: Type.Optional(Type.Integer({ minimum: 1, description: "Read the innermost symbol containing this 1-based line. Combine with symbol to disambiguate duplicate names." })),
+	column: Type.Optional(Type.Integer({ minimum: 1, description: "Optional 1-based UTF-16 column with line, to distinguish symbols on the same line." })),
+	symbol: Type.Optional(Type.String({ minLength: 1, maxLength: 256, description: "Exact symbol name or qualified name, for example Server.run. Omit both symbol and line to list a symbol outline." })),
+	parent: Type.Optional(Type.Integer({ minimum: 0, maximum: 20, description: "Move outward this many enclosing symbols after selection (default 0)." })),
+	context: Type.Optional(Type.Integer({ minimum: 0, maximum: 20, description: "Extra whole lines before and after the selected symbol (default 0)." })),
+	offset: Type.Optional(Type.Integer({ minimum: 1, description: "1-based position within the selected symbol/context or outline, not a file line. Use the exact continuation call from a partial result." })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 1800, description: "Maximum source lines (default 1000) or outline entries (default 50). Output also has a 48 KiB hard limit." })),
+});
+export type ReadSymbolInput = Static<typeof readSymbolSchema>;
+
+export interface VisibleSource {
+	startLine: number;
+	endLine: number;
+	startOffset: number;
+	endOffset: number;
+}
+export interface ReadSymbolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: {
+		mode: "symbol" | "outline";
+		snapshot: string;
+		symbol?: SourceSymbol;
+		visible?: VisibleSource;
+		complete: boolean;
+		nextCall?: ReadSymbolInput;
+	};
+}
+const MAX_OUTPUT_BYTES = 48 * 1024;
+const MAX_OUTPUT_LINES = 1950;
+const label = (text: string) => JSON.stringify(text.length > 300 ? `${text.slice(0, 297)}…` : text);
+const callText = (input: ReadSymbolInput) => `read_symbol ${JSON.stringify(input)}`;
+
+export function validateReadSymbolInput(input: ReadSymbolInput): void {
+	if (!input || typeof input.path !== "string" || !input.path.length || input.path.length > 4096) throw new Error("read_symbol requires a non-empty path of at most 4096 characters.");
+	if (input.symbol !== undefined && (typeof input.symbol !== "string" || !input.symbol.trim() || input.symbol.length > 256)) throw new Error("read_symbol symbol must be a non-empty name of at most 256 characters.");
+	for (const [key, min, max] of [["line", 1, Number.MAX_SAFE_INTEGER], ["column", 1, Number.MAX_SAFE_INTEGER], ["parent", 0, 20], ["context", 0, 20], ["offset", 1, Number.MAX_SAFE_INTEGER], ["limit", 1, 1800]] as const) {
+		const value = input[key];
+		if (value !== undefined && (!Number.isSafeInteger(value) || value < min || value > max)) throw new Error(`read_symbol ${key} must be an integer from ${min} to ${max}.`);
+	}
+	if (input.column !== undefined && input.line === undefined) throw new Error("read_symbol column requires line.");
+	if ((input.parent || input.context) && input.line === undefined && input.symbol === undefined) throw new Error("read_symbol parent/context requires a line or symbol selector; omit them to get an outline.");
+}
+
+function candidateLine(path: string, symbol: SourceSymbol): string {
+	return `- ${label(symbol.qualifiedName)} (${symbol.kind}), lines ${symbol.startLine}-${symbol.endLine}. ${callText({ path, line: symbol.startLine, column: symbol.startColumn, symbol: symbol.qualifiedName.length <= 256 ? symbol.qualifiedName : undefined })}`;
+}
+
+/** Non-copyable preview for failed selection; never presented as a complete symbol. */
+function fallbackContext(input: ReadSymbolInput, content: string, reason: string, atLine = input.line ?? 1): Error {
+	const lines = content.split("\n");
+	const center = Math.min(Math.max(atLine, 1), lines.length);
+	const start = Math.max(1, center - 5);
+	const end = Math.min(lines.length, center + 10);
+	const preview = lines.slice(start - 1, end).map((line, index) => `${start + index}: ${line.length > 240 ? `${line.slice(0, 240)}… [line clipped]` : line}`).join("\n");
+	return new Error(`${reason}\nFile has ${lines.length} lines. Preview only, not a complete symbol or retryable edit snippet:\n${preview}\nNext: read ${JSON.stringify({ path: input.path, offset: start, limit: end - start + 1 })}`);
+}
+
+function inside(symbol: SourceSymbol, line: number, column?: number): boolean {
+	if (line < symbol.startLine || line > symbol.endLine) return false;
+	if (column !== undefined && ((line === symbol.startLine && column < symbol.startColumn) || (line === symbol.endLine && column >= symbol.endColumn))) return false;
+	return true;
+}
+
+function selectSymbol(input: ReadSymbolInput, symbols: SourceSymbol[]): SourceSymbol {
+	let matches = symbols.filter((symbol) =>
+		(input.symbol === undefined || symbol.name === input.symbol || symbol.qualifiedName === input.symbol) &&
+		(input.line === undefined || inside(symbol, input.line, input.column)),
+	);
+	if (input.symbol === undefined) {
+		// Keep innermost declarations, but never choose arbitrarily between siblings.
+		const matched = new Set(matches);
+		const ancestors = new Set<SourceSymbol>();
+		// Parents precede children in the index. Propagate once in reverse,
+		// rather than walking every ancestor chain in deeply nested source.
+		for (let index = symbols.length - 1; index >= 0; index--) {
+			const symbol = symbols[index];
+			if (symbol.parent !== undefined && (matched.has(symbol) || ancestors.has(symbol))) ancestors.add(symbols[symbol.parent]);
+		}
+		matches = matches.filter((symbol) => !ancestors.has(symbol));
+	}
+	if (matches.length !== 1) {
+		const candidates = matches.length ? matches : [...symbols].sort((a, b) => {
+			if (input.line !== undefined) return Math.abs(a.startLine - input.line) - Math.abs(b.startLine - input.line);
+			const query = input.symbol?.toLowerCase() ?? "";
+			return Number(b.qualifiedName.toLowerCase().includes(query)) - Number(a.qualifiedName.toLowerCase().includes(query));
+		});
+		throw new Error([
+			matches.length ? `Ambiguous symbol selection: ${matches.length} candidates. No symbol was selected.` : "No matching symbol. Names are exact and case-sensitive; no nearby symbol was selected automatically.",
+			...candidates.slice(0, 8).map((symbol) => candidateLine(input.path, symbol)),
+			...(candidates.length > 8 ? [`${candidates.length - 8} more candidates omitted.`] : []),
+			`Next: choose a candidate call above, or list the outline with ${callText({ path: input.path })}.`,
+		].join("\n"));
+	}
+	let selected = matches[0];
+	for (let depth = 0; depth < (input.parent ?? 0); depth++) {
+		if (selected.parent === undefined) throw new Error(`No enclosing symbol at parent=${input.parent}. Outermost available: ${candidateLine(input.path, selected)}\nRetry with a smaller parent value.`);
+		selected = symbols[selected.parent];
+	}
+	return selected;
+}
+
+function fits(text: string): boolean {
+	return Buffer.byteLength(text, "utf8") <= MAX_OUTPUT_BYTES && text.split("\n").length <= MAX_OUTPUT_LINES;
+}
+
+/** Pure snapshot-to-result path, also used to verify stored read evidence. */
+export async function buildSymbolRead(input: ReadSymbolInput, content: string, signal?: AbortSignal): Promise<ReadSymbolResult> {
+	validateReadSymbolInput(input);
+	const lines = content.split("\n");
+	if (input.line !== undefined && input.line > lines.length) throw fallbackContext(input, content, `line=${input.line} is beyond EOF. Valid lines: 1-${lines.length}.`);
+	if (input.column !== undefined && input.column > lines[input.line! - 1].length + 1) throw fallbackContext(input, content, `column=${input.column} is outside line ${input.line}.`);
+	const parserPath = resolveToolPath(input.path, "/");
+	if (!languageForPath(parserPath)) throw fallbackContext(input, content, `Unsupported source type. read_symbol supports ${SUPPORTED_LANGUAGES}. Use read for this file.`);
+	let index: Awaited<ReturnType<typeof indexSymbols>>;
+	try { index = await indexSymbols(parserPath, content, signal); }
+	catch (error) {
+		signal?.throwIfAborted();
+		throw fallbackContext(input, content, `Symbol parser unavailable or analysis limit reached: ${error instanceof Error ? error.message.slice(0, 500) : "unknown parser error"}. Use read instead.`);
+	}
+	signal?.throwIfAborted();
+	if (index.errorLine !== undefined) throw fallbackContext(input, content, `Syntax error or incomplete syntax near line ${index.errorLine}; complete symbol boundaries are not reliable.`, input.line ?? index.errorLine);
+	const snapshot = createHash("sha256").update(content).digest("hex");
+	const header = `Source ${label(input.path)} (${lines.length} lines). Snapshot sha256:${snapshot}`;
+	const offset = input.offset ?? 1;
+	if (input.line === undefined && input.symbol === undefined) {
+		const total = index.symbols.length;
+		if (offset > Math.max(1, total)) throw new Error(`Outline offset=${offset} is beyond ${total} entries. Next: ${callText({ ...input, offset: Math.max(1, total - 49) })}`);
+		const entries: string[] = [];
+		let cursor = offset - 1;
+		for (; cursor < Math.min(total, offset - 1 + (input.limit ?? 50)); cursor++) {
+			const entry = candidateLine(input.path, index.symbols[cursor]);
+			if (!fits(`${header}\n${entries.join("\n")}\n${entry}\n${" ".repeat(6000)}`)) break;
+			entries.push(entry);
+		}
+		const nextCall = cursor < total ? { ...input, offset: cursor + 1 } : undefined;
+		const text = `${header}\nSymbol outline: ${total} declarations, ${entries.length} shown.${total === 0 ? " No symbols found; use read for source text." : ""}\n${entries.join("\n")}${nextCall ? `\nMore entries. Next: ${callText(nextCall)}` : ""}`;
+		return { content: [{ type: "text", text }], details: { mode: "outline", snapshot, complete: !nextCall, nextCall } };
+	}
+	if (!index.symbols.length) throw fallbackContext(input, content, "No symbol declarations found in this file.");
+	const selected = selectSymbol(input, index.symbols);
+	const start = Math.max(1, selected.startLine - (input.context ?? 0));
+	const end = Math.min(lines.length, selected.endLine + (input.context ?? 0));
+	const count = end - start + 1;
+	if (offset > count) throw new Error(`Symbol ${label(selected.qualifiedName)} spans lines ${selected.startLine}-${selected.endLine}; selected region has ${count} lines. offset=${offset} is outside it. Next: ${callText({ ...input, offset: 1 })}`);
+	const firstLine = start + offset - 1;
+	let lastLine = Math.min(end, firstLine + (input.limit ?? 1000) - 1);
+	const parents: string[] = [];
+	let parent = selected.parent;
+	while (parent !== undefined && parents.length < 20) { parents.unshift(label(index.symbols[parent].qualifiedName)); parent = index.symbols[parent].parent; }
+	const prefix = `${header}\nSymbol ${label(selected.qualifiedName)} (${selected.kind}), lines ${selected.startLine}-${selected.endLine}.${parents.length ? `\nEnclosing: ${parents.join(" > ")}` : ""}`;
+	let text = "";
+	let snippet = "";
+	let nextCall: ReadSymbolInput | undefined;
+	// Whole-line pages only. Account for fences, metadata, and continuation JSON.
+	while (lastLine >= firstLine) {
+		snippet = lines.slice(firstLine - 1, lastLine).join("\n");
+		const fence = fenceFor(snippet);
+		nextCall = lastLine < end ? { ...input, offset: lastLine - start + 2 } : undefined;
+		text = `${prefix}\nShowing file lines ${firstLine}-${lastLine} of selected lines ${start}-${end}. ${firstLine === start && lastLine === end ? "Complete selection." : "Partial selection; do not treat this page as the whole symbol."}\n\n${fence}\n${snippet}\n${fence}${nextCall ? `\n\nNext: ${callText(nextCall)}` : ""}`;
+		if (fits(text)) break;
+		// Remove a proportional chunk first; small pages shrink one line at a time.
+		lastLine -= Math.max(1, Math.floor((lastLine - firstLine + 1) / 4));
+	}
+	if (lastLine < firstLine) throw fallbackContext(input, content, `File line ${firstLine} cannot fit as a complete line in the 48 KiB output budget. No partial edit snippet was returned.`, firstLine);
+	const spans = getLineSpans(content);
+	const startOffset = spans[firstLine - 1]?.start ?? content.length;
+	return {
+		content: [{ type: "text", text }],
+		details: {
+			mode: "symbol", snapshot, symbol: selected,
+			visible: { startLine: firstLine, endLine: lastLine, startOffset, endOffset: startOffset + snippet.length },
+			complete: firstLine === start && lastLine === end, nextCall,
+		},
+	};
+}
+
+export async function executeReadSymbol(input: ReadSymbolInput, signal: AbortSignal | undefined, ctx: Pick<ExtensionContext, "cwd">): Promise<ReadSymbolResult> {
+	validateReadSymbolInput(input);
+	const path = resolveToolPath(input.path, ctx.cwd);
+	let content: string;
+	try { content = await readSource(path, signal); }
+	catch (error) { signal?.throwIfAborted(); throw new Error(boundCompleteOutput(await sourceReadError(path, error))); }
+	try { return await buildSymbolRead(input, content, signal); }
+	catch (error) {
+		signal?.throwIfAborted();
+		throw new Error(boundCompleteOutput(error instanceof Error ? error.message : String(error)));
+	}
+}
+
+export function registerReadSymbolTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "read_symbol", label: "read_symbol",
+		description: `Read a complete function, method, class, or type from a local source file by containing line or exact symbol name. Supports ${SUPPORTED_LANGUAGES}. With path only, lists a symbol outline. Includes enclosing names, exact source ranges, and actionable failure context. Output is bounded to 48 KiB/1950 lines; partial results include an exact continuation call. Does not replace read for ordinary text or images.`,
+		promptSnippet: "Read whole source symbols by line/name, or list a file's symbol outline",
+		promptGuidelines: [
+			"Use read_symbol with path and line after grep/edit identifies a code location, instead of guessing successive read offsets to find the function boundary.",
+			"Use read_symbol with symbol for an exact name or qualified name; use path alone for an outline. Use parent to include an enclosing function or class.",
+			"For read_symbol partial output, use the supplied continuation arguments. offset is relative to the selection, not a file line. Only displayed source is evidence for edit.",
+		],
+		parameters: readSymbolSchema,
+		async execute(_id, input, signal, _onUpdate, ctx) { return executeReadSymbol(input, signal, ctx); },
+	});
+}

package/src/similarity.ts

@@ -3,16 +3,20 @@
  * failed oldText almost matched.
  */
 
-import { toFuzzyLines } from "./text.ts";
+import { normalizeForFuzzyMatch, normalizeToLF } from "./text.ts";
 
 export interface AlignOp {
-	type: "equal" | "changed" | "file-only" | "old-only";
-	/** 1-based line number in the file (for equal/changed/file-only). */
+	type: "equal" | "similar" | "changed" | "file-only" | "old-only";
+	/** 1-based line number in the file (for equal/similar/changed/file-only). */
 	fileLine?: number;
+	/** Original LF-normalized file text, never fuzzy-normalized. */
 	fileText?: string;
 	/** 1-based line number in the model-provided oldText. */
 	oldLine?: number;
+	/** Original LF-normalized oldText, never fuzzy-normalized. */
 	oldText?: string;
+	/** Heuristic similarity for aligned pairs. */
+	similarity?: number;
 }
 
 export interface ClosestRegion {
@@ -21,10 +25,15 @@ export interface ClosestRegion {
 	/** 0..1 order-preserving, one-to-one line similarity. */
 	score: number;
 	ops: AlignOp[];
+	/** Number of exactly equal original lines. */
 	equalCount: number;
 	totalOldLines: number;
 	/** oldText was truncated for comparison (very large oldText). */
 	truncated: boolean;
+	/** Best distinct, non-overlapping competitor, when retained by the bounded search. */
+	competitor?: { startLine: number; endLine: number; score: number };
+	/** A discarded window was too competitive to prove a safe score margin. */
+	competitionIncomplete: boolean;
 }
 
 interface PreparedLine {
@@ -42,15 +51,28 @@ function prepareLine(text: string): PreparedLine {
 	return { text, grams, gramCount: Math.max(0, text.length - 1) };
 }
 
+class WorkBudget {
+	private remaining: number;
+	constructor(remaining: number) {
+		this.remaining = remaining;
+	}
+	spend(amount: number): boolean {
+		this.remaining -= amount;
+		return this.remaining >= 0;
+	}
+}
+
 /** Dice coefficient over character bigrams; 1.0 for identical strings. */
 export function lineSimilarity(a: string, b: string): number {
 	return preparedSimilarity(prepareLine(a), prepareLine(b));
 }
 
-function preparedSimilarity(a: PreparedLine, b: PreparedLine): number {
+function preparedSimilarity(a: PreparedLine, b: PreparedLine, budget?: WorkBudget): number {
+	if (budget && !budget.spend(1)) throw new Error("similarity-work-budget-exhausted");
 	if (a.text === b.text) return 1;
 	if (a.gramCount === 0 || b.gramCount === 0) return 0;
 	const [small, large] = a.grams.size <= b.grams.size ? [a.grams, b.grams] : [b.grams, a.grams];
+	if (budget && !budget.spend(small.size)) throw new Error("similarity-work-budget-exhausted");
 	let overlap = 0;
 	for (const [gram, count] of small) {
 		const other = large.get(gram);
@@ -61,7 +83,10 @@ function preparedSimilarity(a: PreparedLine, b: PreparedLine): number {
 
 const MAX_COMPARE_LINES = 300;
 const MAX_SEARCH_FILE_LINES = 10_000;
-const MAX_CANDIDATE_WINDOWS = 24;
+const MAX_CANDIDATE_WINDOWS = 48;
+const MAX_QUERY_BYTES = 128 * 1024;
+const MAX_LINE_CHARS = 16 * 1024;
+const MAX_SIMILARITY_WORK = 20_000_000;
 const MIN_SCORE = 0.3;
 const MATCH_THRESHOLD = 0.75;
 
@@ -71,81 +96,122 @@ interface CandidateWindow {
 	positionalScore: number;
 }
 
+interface ScoredWindow extends CandidateWindow {
+	score: number;
+}
+
+function originalLines(text: string): string[] {
+	const lines = normalizeToLF(text).split("\n");
+	// Remove only the synthetic segment after a terminal newline. Do not remove
+	// a real, unterminated whitespace-only line.
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+
 /**
- * Find the window of file lines most similar to oldText.
- *
- * The first pass ranks every window using cheap positional similarity. Only a
- * small bounded set of candidates receives the more expensive sequence score.
- * The sequence score is order-preserving and one-to-one, so repeated query
- * lines cannot all claim the same file line.
+ * Find the best window and a distinct runner-up under explicit input/work
+ * budgets. Returning null is the safe fallback when a budget is exhausted.
  */
 export function findClosestRegion(content: string, oldText: string): ClosestRegion | null {
-	const allQLines = toFuzzyLines(oldText);
-	const cLines = toFuzzyLines(content);
-	if (allQLines.length === 0 || cLines.length === 0 || cLines.length > MAX_SEARCH_FILE_LINES) return null;
+	if (Buffer.byteLength(oldText, "utf8") > MAX_QUERY_BYTES) return null;
+	const originalQ = originalLines(oldText);
+	const originalContent = originalLines(content);
+	if (originalQ.length === 0 || originalContent.length === 0 || originalContent.length > MAX_SEARCH_FILE_LINES) return null;
+	if ([...originalQ, ...originalContent].some((line) => line.length > MAX_LINE_CHARS)) return null;
 
+	const allQLines = originalQ.map(normalizeForFuzzyMatch);
+	const cLines = originalContent.map(normalizeForFuzzyMatch);
 	const truncated = allQLines.length > MAX_COMPARE_LINES;
 	const q = truncated ? allQLines.slice(0, MAX_COMPARE_LINES) : allQLines;
+	const qOriginal = truncated ? originalQ.slice(0, MAX_COMPARE_LINES) : originalQ;
 	const L = q.length;
 	const sizes = [...new Set([L - 1, L, L + 1].filter((size) => size >= 1 && size <= cLines.length))];
 	const preparedQ = q.map(prepareLine);
 	const preparedContent = cLines.map(prepareLine);
 	const candidates: CandidateWindow[] = [];
+	let discardedMaxPositionalScore = -1;
+	const budget = new WorkBudget(MAX_SIMILARITY_WORK);
 
-	for (const size of sizes) {
-		for (let start = 0; start + size <= cLines.length; start++) {
-			const pairs = Math.min(L, size);
-			let sum = 0;
-			for (let i = 0; i < pairs; i++) {
-				sum += preparedSimilarity(preparedQ[i], preparedContent[start + i]);
+	try {
+		for (const size of sizes) {
+			for (let start = 0; start + size <= cLines.length; start++) {
+				const pairs = Math.min(L, size);
+				let sum = 0;
+				for (let i = 0; i < pairs; i++) {
+					sum += preparedSimilarity(preparedQ[i], preparedContent[start + i], budget);
+				}
+				const discarded = keepCandidate(candidates, { start, size, positionalScore: sum / Math.max(L, size) });
+				if (discarded !== undefined) discardedMaxPositionalScore = Math.max(discardedMaxPositionalScore, discarded);
 			}
-			keepCandidate(candidates, { start, size, positionalScore: sum / Math.max(L, size) });
 		}
-	}
 
-	let bestScore = -1;
-	let best: CandidateWindow | undefined;
-	for (const candidate of candidates) {
-		const window = preparedContent.slice(candidate.start, candidate.start + candidate.size);
-		const score = sequenceSimilarity(preparedQ, window);
-		if (score > bestScore || (score === bestScore && candidate.positionalScore > (best?.positionalScore ?? -1))) {
-			bestScore = score;
-			best = candidate;
-		}
+		const scored: ScoredWindow[] = candidates.map((candidate) => ({
+			...candidate,
+			score: sequenceSimilarity(
+				preparedQ,
+				preparedContent.slice(candidate.start, candidate.start + candidate.size),
+				budget,
+			),
+		}));
+		scored.sort(
+			(a, b) => b.score - a.score || b.positionalScore - a.positionalScore || a.start - b.start || a.size - b.size,
+		);
+		const best = scored[0];
+		if (!best || best.score < MIN_SCORE) return null;
+		const bestEnd = best.start + best.size;
+		const runner = scored.find((candidate) => {
+			const candidateEnd = candidate.start + candidate.size;
+			return candidateEnd <= best.start || candidate.start >= bestEnd;
+		});
+
+		const windowLines = cLines.slice(best.start, bestEnd);
+		const windowOriginal = originalContent.slice(best.start, bestEnd);
+		const ops = alignLines(q, windowLines, qOriginal, windowOriginal, best.start, budget);
+		return {
+			startLine: best.start + 1,
+			endLine: bestEnd,
+			score: best.score,
+			ops,
+			equalCount: ops.filter((op) => op.type === "equal").length,
+			totalOldLines: L,
+			truncated,
+			competitor: runner
+				? { startLine: runner.start + 1, endLine: runner.start + runner.size, score: runner.score }
+				: undefined,
+			competitionIncomplete: discardedMaxPositionalScore >= best.positionalScore - MIN_DIRECT_POSITIONAL_GAP,
+		};
+	} catch (error) {
+		if (error instanceof Error && error.message === "similarity-work-budget-exhausted") return null;
+		throw error;
 	}
-	if (!best || bestScore < MIN_SCORE) return null;
-
-	const windowLines = cLines.slice(best.start, best.start + best.size);
-	const ops = alignLines(q, windowLines, best.start);
-	return {
-		startLine: best.start + 1,
-		endLine: best.start + best.size,
-		score: bestScore,
-		ops,
-		equalCount: ops.filter((op) => op.type === "equal").length,
-		totalOldLines: L,
-		truncated,
-	};
 }
 
-function keepCandidate(candidates: CandidateWindow[], candidate: CandidateWindow): void {
+const MIN_DIRECT_POSITIONAL_GAP = 0.1;
+
+/** Return the positional score of any candidate discarded by the bounded heap. */
+function keepCandidate(candidates: CandidateWindow[], candidate: CandidateWindow): number | undefined {
 	if (candidates.length < MAX_CANDIDATE_WINDOWS) {
 		candidates.push(candidate);
-		candidates.sort((a, b) => a.positionalScore - b.positionalScore);
-		return;
+		candidates.sort((a, b) => a.positionalScore - b.positionalScore || b.start - a.start || b.size - a.size);
+		return undefined;
 	}
-	if (candidate.positionalScore <= candidates[0].positionalScore) return;
+	const worst = candidates[0];
+	if (
+		candidate.positionalScore < worst.positionalScore ||
+		(candidate.positionalScore === worst.positionalScore && candidate.start >= worst.start)
+	) return candidate.positionalScore;
 	candidates[0] = candidate;
-	candidates.sort((a, b) => a.positionalScore - b.positionalScore);
+	candidates.sort((a, b) => a.positionalScore - b.positionalScore || b.start - a.start || b.size - a.size);
+	return worst.positionalScore;
 }
 
 /** Weighted LCS: lines are matched at most once and in source order. */
-function sequenceSimilarity(query: PreparedLine[], window: PreparedLine[]): number {
+function sequenceSimilarity(query: PreparedLine[], window: PreparedLine[], budget: WorkBudget): number {
 	let previous = new Float64Array(window.length + 1);
 	for (let i = 1; i <= query.length; i++) {
 		const current = new Float64Array(window.length + 1);
 		for (let j = 1; j <= window.length; j++) {
-			const matched = previous[j - 1] + preparedSimilarity(query[i - 1], window[j - 1]);
+			const matched = previous[j - 1] + preparedSimilarity(query[i - 1], window[j - 1], budget);
 			current[j] = Math.max(previous[j], current[j - 1], matched);
 		}
 		previous = current;
@@ -153,18 +219,21 @@ function sequenceSimilarity(query: PreparedLine[], window: PreparedLine[]): numb
 	return previous[window.length] / Math.max(query.length, window.length);
 }
 
-/**
- * LCS-style alignment between oldText lines and the best window. Lines with
- * similarity >= MATCH_THRESHOLD count as equal; adjacent insert/delete pairs
- * are merged into changed operations for compact diagnostics.
- */
-function alignLines(q: string[], w: string[], wOffset: number): AlignOp[] {
+/** Align fuzzy lines while attaching original strings to every operation. */
+function alignLines(
+	q: string[],
+	w: string[],
+	qOriginal: string[],
+	wOriginal: string[],
+	wOffset: number,
+	budget: WorkBudget,
+): AlignOp[] {
 	const n = q.length;
 	const m = w.length;
 	const preparedQ = q.map(prepareLine);
 	const preparedW = w.map(prepareLine);
 	const similarities = Array.from({ length: n }, (_, i) =>
-		Array.from({ length: m }, (_, j) => preparedSimilarity(preparedQ[i], preparedW[j])),
+		Array.from({ length: m }, (_, j) => preparedSimilarity(preparedQ[i], preparedW[j], budget)),
 	);
 	const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
 	for (let i = n - 1; i >= 0; i--) {
@@ -180,17 +249,25 @@ function alignLines(q: string[], w: string[], wOffset: number): AlignOp[] {
 	let j = 0;
 	while (i < n && j < m) {
 		if (similarities[i][j] >= MATCH_THRESHOLD) {
-			raw.push({ type: "equal", fileLine: wOffset + j + 1, fileText: w[j], oldLine: i + 1, oldText: q[i] });
+			const exact = qOriginal[i] === wOriginal[j];
+			raw.push({
+				type: exact ? "equal" : "similar",
+				fileLine: wOffset + j + 1,
+				fileText: wOriginal[j],
+				oldLine: i + 1,
+				oldText: qOriginal[i],
+				similarity: similarities[i][j],
+			});
 			i++;
 			j++;
 		} else if (dp[i + 1][j] > dp[i][j + 1]) {
-			raw.push({ type: "old-only", oldLine: i + 1, oldText: q[i++] });
+			raw.push({ type: "old-only", oldLine: i + 1, oldText: qOriginal[i++] });
 		} else {
-			raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: w[j++] });
+			raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: wOriginal[j++] });
 		}
 	}
-	while (i < n) raw.push({ type: "old-only", oldLine: i + 1, oldText: q[i++] });
-	while (j < m) raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: w[j++] });
+	while (i < n) raw.push({ type: "old-only", oldLine: i + 1, oldText: qOriginal[i++] });
+	while (j < m) raw.push({ type: "file-only", fileLine: wOffset + j + 1, fileText: wOriginal[j++] });
 
 	const merged: AlignOp[] = [];
 	for (let k = 0; k < raw.length; k++) {

package/src/source-file.ts

@@ -0,0 +1,60 @@
+import { constants } from "node:fs";
+import { open, opendir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { MAX_SOURCE_BYTES } from "./symbols.ts";
+import { normalizeToLF, splitBom } from "./text.ts";
+
+/** Bounded local source read; no silent decoding loss and no special files. */
+export async function readSource(path: string, signal?: AbortSignal): Promise<string> {
+	signal?.throwIfAborted();
+	const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+	try {
+		const stat = await handle.stat();
+		if (!stat.isFile()) throw new Error("The path is not a regular source file.");
+		if (stat.size > MAX_SOURCE_BYTES) throw new Error("Source exceeds the 2 MiB symbol analysis limit; use read with offset/limit.");
+		const buffer = Buffer.alloc(Math.min(stat.size + 1, MAX_SOURCE_BYTES + 1));
+		let length = 0;
+		while (length < buffer.length) {
+			signal?.throwIfAborted();
+			const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+			if (!bytesRead) break;
+			length += bytesRead;
+		}
+		const after = await handle.stat();
+		if (length !== stat.size || stat.size !== after.size || stat.mtimeMs !== after.mtimeMs || stat.ctimeMs !== after.ctimeMs) throw new Error("The source changed during the read; retry read_symbol.");
+		const bytes = buffer.subarray(0, length);
+		let content: string;
+		try { content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes); }
+		catch { throw new Error("The source is not valid UTF-8; convert its encoding before symbol parsing."); }
+		if (bytes.includes(0)) throw new Error("The source contains NUL bytes; binary/UTF-16 input is not supported.");
+		signal?.throwIfAborted();
+		return splitBom(normalizeToLF(content)).text;
+	} finally {
+		await handle.close();
+	}
+}
+
+/** Only inspect a bounded number of siblings; never perform a hidden repo scan. */
+export async function sourceReadError(path: string, error: unknown): Promise<string> {
+	const code = (error as NodeJS.ErrnoException)?.code;
+	const message = error instanceof Error ? error.message.slice(0, 1000) : String(error).slice(0, 1000);
+	const lines = [`Could not read source ${JSON.stringify(path)}: ${message}`];
+	if (code === "ENOENT" || code === "ENOTDIR") {
+		const names: string[] = [];
+		try {
+			const directory = await opendir(dirname(path));
+			let inspected = 0;
+			for await (const entry of directory) {
+				if (entry.isFile()) names.push(entry.name);
+				if (++inspected >= 100) break;
+			}
+		} catch { /* Parent may also be missing or inaccessible. */ }
+		const stem = basename(path).split(".")[0].toLowerCase();
+		names.sort((a, b) => Number(b.toLowerCase().includes(stem)) - Number(a.toLowerCase().includes(stem)) || a.localeCompare(b));
+		if (names.length) lines.push("Nearby file candidates (bounded listing, not automatic path corrections):", ...names.slice(0, 8).map((name) => `  ${JSON.stringify(join(dirname(path), name))}`));
+		lines.push("Verify the path and retry read_symbol; use find/ls if the parent path is wrong.");
+	} else if (code === "EACCES" || code === "EPERM") {
+		lines.push("Check file permissions. Do not retry the same call until access changes.");
+	} else lines.push("Use read for ordinary text, images, or bounded line ranges; no symbol boundaries were returned.");
+	return lines.join("\n");
+}