@oh-my-pi/hashline 16.3.2 → 16.3.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [16.3.3] - 2026-07-02
+
+### Breaking Changes
+
+- Removed SnapshotStore.byHashExact. Consumers should now use byHash, which resolves collisions by returning the most recently recorded version.
+
+### Changed
+
+- Improved patch application robustness by resolving 16-bit snapshot tag collisions to the most recent version instead of rejecting them.
+
+### Fixed
+
+- Fixed frequent edit rejections after a structural-summary read (affecting parseable code over 100 lines) by automatically inlining unseen anchor lines and merging them into the snapshot's seen lines, allowing immediate retries to succeed without requiring a separate range re-read.
+
 ## [16.3.0] - 2026-07-02
 
 ### Changed

package/dist/types/messages.d.ts

@@ -108,13 +108,33 @@ export declare function missingSnapshotTagMessage(sectionPath: string): string;
  * model (and user) learn the corrected path and stop reusing the wrong one.
  */
 export declare function pathRecoveredFromTagMessage(authoredPath: string, resolvedPath: string, tag: string): string;
+/** One anchored line whose actual content is being surfaced in an error message. */
+export interface RevealedLine {
+    line: number;
+    text: string;
+}
+/**
+ * Content preview handed to {@link unseenLinesMessage}. `lines` are the
+ * unseen anchor lines whose actual file content we surface inline (from the
+ * tagged snapshot the caller matched). `truncated` = true means the anchor
+ * range exceeded the inline reveal cap; the caller only revealed a prefix
+ * and the remaining unseen lines still require a range re-read.
+ */
+export interface UnseenLinesReveal {
+    lines: readonly RevealedLine[];
+    truncated: boolean;
+}
 /**
  * An anchored edit referenced lines the read that minted the cited tag never
  * displayed (a partial range, or a structural summary that collapsed bodies).
  * Editing lines you have not read is the off-by-memory failure that mangles
- * files; reject and make the model re-read those exact lines first.
+ * files. When `reveal.lines` is non-empty, the caller has already inlined the
+ * actual file content at those lines and merged them into the snapshot's
+ * seen-line set, so the message points the model at a straight retry with the
+ * same `[path#tag]` header; when the reveal is empty or truncated, the
+ * message falls back to instructing a range re-read.
  */
-export declare function unseenLinesMessage(sectionPath: string, unseenLines: readonly number[], tag: string): string;
+export declare function unseenLinesMessage(sectionPath: string, unseenLines: readonly number[], tag: string, reveal?: UnseenLinesReveal): string;
 /** Op kind of a deferred block edit, for {@link blockSingleLineMessage}. */
 export type BlockOp = "replace" | "delete" | "insert_after";
 /**

package/dist/types/snapshots.d.ts

@@ -23,8 +23,8 @@ export interface Snapshot {
 }
 /**
  * Storage seam for full-file version snapshots. The patcher calls {@link head}
- * for the latest version of a path and {@link byHashExact} when it needs the
- * specific historical version a section's stale tag names.
+ * for the latest version of a path and {@link byHash} when it needs the
+ * historical version a section's stale tag names.
  */
 export declare abstract class SnapshotStore {
     /** Most-recently recorded version for `path`, or `null` if none. */
@@ -32,25 +32,13 @@ export declare abstract class SnapshotStore {
     /**
      * Recorded version for `path` whose tag equals `hash`, or `null`. When two
      * distinct texts collide on the 16-bit tag, returns the most-recently
-     * recorded one; callers that treat the tag as content identity must use
-     * {@link byHashExact} (or verify {@link Snapshot.text} via {@link byContent}).
+     * recorded one.
      */
     abstract byHash(path: string, hash: string): Snapshot | null;
-    /**
-     * Collision-safe {@link byHash}: the single retained version for `path`
-     * whose tag equals `hash`, or `null` when none is retained OR when two or
-     * more distinct texts collide on the tag. In the collision case there is
-     * no way to know which retained text the model's line anchors were minted
-     * against, so consumers that replay anchors (recovery, previews) must
-     * refuse rather than pick one.
-     */
-    abstract byHashExact(path: string, hash: string): Snapshot | null;
     /**
      * Recorded version for `path` whose {@link Snapshot.text} equals `fullText`,
-     * or `null`. Disambiguates hash collisions where two distinct file states
-     * share the same 4-hex tag: the patcher consults this before taking the
-     * no-drift path so a colliding live text is never accepted as the exact
-     * snapshot the model's line anchors were minted against.
+     * or `null`. The patcher uses it on the no-drift path to attach seen-line
+     * provenance to the exact text the model read.
      */
     abstract byContent(path: string, fullText: string): Snapshot | null;
     /**
@@ -116,7 +104,6 @@ export declare class InMemorySnapshotStore extends SnapshotStore {
     constructor(options?: InMemorySnapshotStoreOptions);
     head(path: string): Snapshot | null;
     byHash(path: string, hash: string): Snapshot | null;
-    byHashExact(path: string, hash: string): Snapshot | null;
     byContent(path: string, fullText: string): Snapshot | null;
     findByHash(hash: string): Snapshot[];
     record(path: string, fullText: string, seenLines?: Iterable<number>): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "16.3.2",
+	"version": "16.3.4",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",

package/src/messages.ts

@@ -223,21 +223,66 @@ function formatLineRanges(lines: readonly number[]): string {
 	return parts.join(", ");
 }
 
+/** One anchored line whose actual content is being surfaced in an error message. */
+export interface RevealedLine {
+	line: number;
+	text: string;
+}
+
+/**
+ * Content preview handed to {@link unseenLinesMessage}. `lines` are the
+ * unseen anchor lines whose actual file content we surface inline (from the
+ * tagged snapshot the caller matched). `truncated` = true means the anchor
+ * range exceeded the inline reveal cap; the caller only revealed a prefix
+ * and the remaining unseen lines still require a range re-read.
+ */
+export interface UnseenLinesReveal {
+	lines: readonly RevealedLine[];
+	truncated: boolean;
+}
+
 /**
  * An anchored edit referenced lines the read that minted the cited tag never
  * displayed (a partial range, or a structural summary that collapsed bodies).
  * Editing lines you have not read is the off-by-memory failure that mangles
- * files; reject and make the model re-read those exact lines first.
+ * files. When `reveal.lines` is non-empty, the caller has already inlined the
+ * actual file content at those lines and merged them into the snapshot's
+ * seen-line set, so the message points the model at a straight retry with the
+ * same `[path#tag]` header; when the reveal is empty or truncated, the
+ * message falls back to instructing a range re-read.
  */
-export function unseenLinesMessage(sectionPath: string, unseenLines: readonly number[], tag: string): string {
+export function unseenLinesMessage(
+	sectionPath: string,
+	unseenLines: readonly number[],
+	tag: string,
+	reveal: UnseenLinesReveal = { lines: [], truncated: false },
+): string {
 	const ranges = formatLineRanges(unseenLines);
 	const selector = ranges.replace(/, /g, ",");
-	return (
+	const header =
 		`This edit anchors to lines ${ranges} of ${sectionPath} that ` +
 		`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}${tag}${HL_FILE_SUFFIX} never displayed (it showed a ` +
-		`partial range, a search hit, or a folded summary). Re-read them in full first with a ranged read like ` +
-		`\`${sectionPath}:${selector}\` — it skips summarization and mints a fresh tag (a plain re-read just re-folds ` +
-		`them) — then re-issue the edit.`
+		`partial range, a search hit, or a folded summary).`;
+	if (reveal.lines.length === 0) {
+		return (
+			`${header} Re-read them in full first with a ranged read like ` +
+			`\`${sectionPath}:${selector}\` — it skips summarization and mints a fresh tag (a plain re-read just re-folds ` +
+			`them) — then re-issue the edit.`
+		);
+	}
+	const preview = reveal.lines.map(({ line, text }) => `  ${formatNumberedLine(line, text)}`).join("\n");
+	if (reveal.truncated) {
+		return (
+			`${header} Preview of the actual file content at the first ${reveal.lines.length} unseen line(s):\n${preview}\n` +
+			`The range exceeds the inline preview cap — re-read the remainder with \`${sectionPath}:${selector}\` before ` +
+			`re-issuing the edit.`
+		);
+	}
+	return (
+		`${header} Actual file content at those lines:\n${preview}\n` +
+		`Verify the content matches what you intend to touch, then re-issue the edit with the same ` +
+		`${HL_FILE_PREFIX}path${HL_FILE_HASH_SEP}tag${HL_FILE_SUFFIX} header — a straight retry now succeeds without a re-read. ` +
+		`If the content does NOT match, fix your line numbers.`
 	);
 }
 

package/src/patcher.ts

@@ -33,6 +33,7 @@ import {
 	HEADTAIL_DRIFT_WARNING,
 	missingSnapshotTagMessage,
 	pathRecoveredFromTagMessage,
+	type RevealedLine,
 	unseenLinesMessage,
 } from "./messages";
 import { MismatchError } from "./mismatch";
@@ -41,6 +42,26 @@ import { Recovery, type RecoveryResult } from "./recovery";
 import type { Snapshot, SnapshotStore } from "./snapshots";
 import type { ApplyResult, BlockResolution, BlockResolver, Edit, FileOp } from "./types";
 
+/**
+ * Upper bound on the number of unseen anchor lines whose actual file content
+ * we inline into a rejection error (see {@link Patcher.assertSeenLines}). Big
+ * enough to fit the common "edit a whole function body" retry path in one
+ * message, small enough to keep the error human-readable when the model
+ * over-anchors and to preserve the "re-read first" fallback for genuinely
+ * blind wide edits (only the revealed prefix gets merged into `seenLines`).
+ */
+const SEEN_LINE_REVEAL_CAP = 40;
+
+/**
+ * Per-revealed-line character cap. Matches the read/search column cap so a
+ * revealed anchor line can never dump a minified megabyte-wide bundle line
+ * into the tool error, TUI, and model context. Lines longer than the cap
+ * are trimmed to `cap` characters plus an `…` marker AND flag the entire
+ * reveal as truncated so no line joins `seenLines` — the model must re-read
+ * the range to prove it saw the full width.
+ */
+const SEEN_LINE_REVEAL_MAX_COLUMNS = 512;
+
 export interface PatcherOptions {
 	/** Storage backend used for all reads and writes. */
 	fs: Filesystem;
@@ -486,13 +507,55 @@ export class Patcher {
 	 * externally minted or aged out), so the edit applies as before. Only runs
 	 * on the no-drift path, where anchor line numbers index the tagged content
 	 * 1:1.
+	 *
+	 * The rejection inlines the actual file content at the unseen anchor lines
+	 * (from `matchedSnapshot.text`, which by definition equals the live
+	 * normalized content) so the model can verify what it was about to touch.
+	 * When the reveal covers EVERY unseen anchor line in full width
+	 * (`truncated === false`) those lines also merge into the snapshot's
+	 * seen-line set, so a straight retry with the same `[path#tag]` header
+	 * succeeds without a follow-up range read — the content the model
+	 * received in the error IS proof it has now seen those lines. When the
+	 * anchor range exceeds {@link SEEN_LINE_REVEAL_CAP} lines OR any
+	 * revealed line exceeds {@link SEEN_LINE_REVEAL_MAX_COLUMNS} characters
+	 * (`truncated === true`), NO lines merge: the message keeps the
+	 * range-re-read guidance intact and the model cannot piecewise-reveal
+	 * its way past the guard across multiple retries
+	 * (over-cap retry → tail reveal → next retry applies), nor coax the tool
+	 * into dumping a minified megabyte-wide line into the error preview.
 	 */
 	#assertSeenLines(section: PatchSection, expected: string, matchedSnapshot: Snapshot | null): void {
 		const seen = matchedSnapshot?.seenLines;
 		if (!seen || seen.size === 0) return;
 		const unseen = section.collectAnchorLines().filter(line => !seen.has(line));
 		if (unseen.length === 0) return;
-		throw new Error(unseenLinesMessage(section.path, unseen, expected));
+		const sourceLines = matchedSnapshot?.text.split("\n") ?? [];
+		const revealed: RevealedLine[] = [];
+		const revealCount = Math.min(unseen.length, SEEN_LINE_REVEAL_CAP);
+		let columnTruncated = false;
+		for (let i = 0; i < revealCount; i++) {
+			const line = unseen[i];
+			// Out-of-range anchors are caught by parse/apply with a better
+			// message; skip them here so they never join the revealed set.
+			if (line < 1 || line > sourceLines.length) continue;
+			const source = sourceLines[line - 1] ?? "";
+			if (source.length > SEEN_LINE_REVEAL_MAX_COLUMNS) {
+				revealed.push({ line, text: `${source.slice(0, SEEN_LINE_REVEAL_MAX_COLUMNS)}…` });
+				columnTruncated = true;
+			} else {
+				revealed.push({ line, text: source });
+			}
+		}
+		const truncated = unseen.length > revealed.length || columnTruncated;
+		// Only merge when the reveal covered every unseen anchor line in full
+		// width. A prefix-truncated reveal would let the model split a blind
+		// edit into <=cap-line retries and land it without ever running the
+		// required range re-read; a column-clipped reveal would leave part of
+		// each line unseen while the model receives an "ok to retry" signal.
+		if (!truncated) {
+			for (const { line } of revealed) seen.add(line);
+		}
+		throw new Error(unseenLinesMessage(section.path, unseen, expected, { lines: revealed, truncated }));
 	}
 	#mismatchError(
 		section: PatchSection,
@@ -521,23 +584,13 @@ export class Patcher {
 	}): ApplyResult {
 		const { section, canonicalPath, exists, normalized, edits } = args;
 		const expected = exists ? section.fileHash : undefined;
-		// A 16-bit tag can collide across two different file states, so equality
-		// on `computeFileHash(normalized) === expected` alone is not enough to
-		// prove the live text IS the snapshot the tag names. Also require that,
-		// when a snapshot for `(path, expected)` is retained, exactly one stored
-		// version carries the tag and its full text matches the live text. If
-		// multiple versions share the tag, the header is ambiguous: there is no
-		// safe way to know which stored text the model's line anchors came from.
-		const storedSnapshotsForTag =
-			expected === undefined
-				? []
-				: this.snapshots.findByHash(expected).filter(snapshot => snapshot.path === canonicalPath);
-		const ambiguousStoredTag = storedSnapshotsForTag.length > 1;
+		// The 4-hex tag is content-derived: when the live text hashes to it,
+		// trust the match and apply directly. `storedSnapshotForTag` feeds the
+		// drift paths below (block resolution, 3-way recovery); on a 16-bit
+		// tag collision it resolves to the most-recently recorded text.
 		const storedSnapshotForTag = expected === undefined ? null : this.snapshots.byHash(canonicalPath, expected);
-		const hashMatches = expected !== undefined && computeFileHash(normalized) === expected;
-		const matchedSnapshot = hashMatches ? this.snapshots.byContent(canonicalPath, normalized) : null;
-		const liveMatches =
-			hashMatches && !ambiguousStoredTag && (storedSnapshotForTag === null || matchedSnapshot !== null);
+		const liveMatches = expected !== undefined && computeFileHash(normalized) === expected;
+		const matchedSnapshot = liveMatches ? this.snapshots.byContent(canonicalPath, normalized) : null;
 
 		// Resolve `replace_block N:` edits to concrete ranges before recovery
 		// runs. Block anchors are expressed against the snapshot the section tag
@@ -552,9 +605,6 @@ export class Patcher {
 		const resolveWarnings: string[] = [];
 		let resolved: readonly Edit[] = edits;
 		if (hasBlockEdit(edits)) {
-			if (ambiguousStoredTag) {
-				throw this.#mismatchError(section, canonicalPath, normalized, expected ?? "", true);
-			}
 			const baseText = expected === undefined || liveMatches ? normalized : storedSnapshotForTag?.text;
 			if (baseText === undefined) {
 				throw this.#mismatchError(section, canonicalPath, normalized, expected ?? "", false);
@@ -590,9 +640,6 @@ export class Patcher {
 			const result = applyEdits(normalized, resolved);
 			return withResolveWarnings({ ...result, warnings: [HEADTAIL_DRIFT_WARNING, ...(result.warnings ?? [])] });
 		}
-		if (ambiguousStoredTag) {
-			throw this.#mismatchError(section, canonicalPath, normalized, expected ?? "", true);
-		}
 		// File drifted: try to replay the edit against the version the tag
 		// names and 3-way-merge it onto the live content.
 		const recovered = this.recovery.tryRecover({

package/src/recovery.ts

@@ -392,11 +392,10 @@ export class Recovery {
 	 */
 	tryRecover(args: RecoveryArgs): RecoveryResult | null {
 		const { path, currentText, fileHash, edits } = args;
-		// Collision-safe lookup: when two retained texts share the 16-bit tag
-		// there is no way to know which one the model's anchors were minted
-		// against — replaying against the wrong collider would land the edit
-		// on unrelated content. Refuse and let the caller reject (re-read).
-		const snapshot = this.store.byHashExact(path, fileHash);
+		// When two retained texts collide on the 16-bit tag, resolve to the
+		// most-recently recorded one; a wrong pick can only land if one of the
+		// merge/remap/session-chain strategies below applies it cleanly.
+		const snapshot = this.store.byHash(path, fileHash);
 		if (!snapshot) return null;
 		const isHead = isHeadSnapshot(this.store.head(path), snapshot);
 		const recoveryWarning = isHead ? RECOVERY_EXTERNAL_WARNING : RECOVERY_SESSION_CHAIN_WARNING;

package/src/snapshots.ts

@@ -11,7 +11,7 @@
  * {@link SnapshotStore.record} with the full normalized text they observed.
  * The store hashes it, dedups against the per-path history, and returns the
  * tag. Consumers (recovery, the patcher) resolve a stale tag back to the
- * recorded full text via {@link SnapshotStore.byHashExact} and 3-way-merge the
+ * recorded full text via {@link SnapshotStore.byHash} and 3-way-merge the
  * would-be edit onto the live content.
  *
  * The abstract base class lets callers plug in whatever storage they like
@@ -49,8 +49,8 @@ export interface Snapshot {
 
 /**
  * Storage seam for full-file version snapshots. The patcher calls {@link head}
- * for the latest version of a path and {@link byHashExact} when it needs the
- * specific historical version a section's stale tag names.
+ * for the latest version of a path and {@link byHash} when it needs the
+ * historical version a section's stale tag names.
  */
 export abstract class SnapshotStore {
 	/** Most-recently recorded version for `path`, or `null` if none. */
@@ -59,27 +59,14 @@ export abstract class SnapshotStore {
 	/**
 	 * Recorded version for `path` whose tag equals `hash`, or `null`. When two
 	 * distinct texts collide on the 16-bit tag, returns the most-recently
-	 * recorded one; callers that treat the tag as content identity must use
-	 * {@link byHashExact} (or verify {@link Snapshot.text} via {@link byContent}).
+	 * recorded one.
 	 */
 	abstract byHash(path: string, hash: string): Snapshot | null;
 
-	/**
-	 * Collision-safe {@link byHash}: the single retained version for `path`
-	 * whose tag equals `hash`, or `null` when none is retained OR when two or
-	 * more distinct texts collide on the tag. In the collision case there is
-	 * no way to know which retained text the model's line anchors were minted
-	 * against, so consumers that replay anchors (recovery, previews) must
-	 * refuse rather than pick one.
-	 */
-	abstract byHashExact(path: string, hash: string): Snapshot | null;
-
 	/**
 	 * Recorded version for `path` whose {@link Snapshot.text} equals `fullText`,
-	 * or `null`. Disambiguates hash collisions where two distinct file states
-	 * share the same 4-hex tag: the patcher consults this before taking the
-	 * no-drift path so a colliding live text is never accepted as the exact
-	 * snapshot the model's line anchors were minted against.
+	 * or `null`. The patcher uses it on the no-drift path to attach seen-line
+	 * provenance to the exact text the model read.
 	 */
 	abstract byContent(path: string, fullText: string): Snapshot | null;
 
@@ -189,20 +176,6 @@ export class InMemorySnapshotStore extends SnapshotStore {
 		return history?.find(version => version.hash === hash) ?? null;
 	}
 
-	byHashExact(path: string, hash: string): Snapshot | null {
-		const history = this.#versions.get(path);
-		if (history === undefined) return null;
-		let match: Snapshot | null = null;
-		for (const version of history) {
-			if (version.hash !== hash) continue;
-			// Two retained versions with one tag are distinct texts by
-			// construction (record() dedups on full-text equality) — ambiguous.
-			if (match !== null) return null;
-			match = version;
-		}
-		return match;
-	}
-
 	byContent(path: string, fullText: string): Snapshot | null {
 		const history = this.#versions.get(path);
 		return history?.find(version => version.text === fullText) ?? null;