@oh-my-pi/hashline 16.2.12 → 16.3.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [16.3.0] - 2026-07-02
+
+### Changed
+
+- Significantly improved performance on large files by optimizing stale-anchor remap validation.
+
+### Fixed
+
+- Fixed an issue where snapshot tag collisions could cause line-anchored edits to be incorrectly applied to unrelated content, improving recovery and edit-preview safety.
+- Fixed tracking of edit anchors when earlier in-session insertions or deletions shift unchanged target lines.
+- Fixed hashline edit guidance and parsing errors for Markdown list rows.
+
 ## [16.2.8] - 2026-06-30
 
 ### Fixed

package/dist/types/messages.d.ts

@@ -21,7 +21,7 @@ export declare const REPLACE_PAIR_COALESCED_WARNING = "Two hunks targeted the sa
 /** Bare body rows auto-converted to literal `+` rows. */
 export declare const BARE_BODY_AUTO_PIPED_WARNING = "Auto-prefixed bare body row(s) with `+`. Body rows must be `+TEXT` literal lines.";
 /** Unified-diff-style `-` row in a hunk body. */
-export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; the range already names the lines being changed. For a literal `-` line, write `+-\u2026`.";
+export declare const MINUS_ROW_REJECTED = "`-` rows are not valid; the range already names the lines being changed. For Markdown bullets or other literal `-` lines, prefix the literal row with `+`: `+- item`.";
 /** Replace hunk with no body. */
 export declare const EMPTY_REPLACE = "`SWAP N.=M:` needs at least one `+TEXT` body row. To delete lines, use `DEL N.=M`.";
 /** `replace_block N:` hunk with no body. */
@@ -87,6 +87,8 @@ export declare const RECOVERY_SESSION_CHAIN_WARNING = "Recovered from a stale fi
  * the chain could still misplace an anchor — hence the verify hedge.
  */
 export declare const RECOVERY_SESSION_REPLAY_WARNING = "Recovered by replaying your edits onto the current file content (a prior in-session edit changed the lines you re-targeted with a stale hash). Verify the diff matches your intent.";
+/** `Recovery`: stale anchors were relocated to unchanged live lines after drift. */
+export declare const RECOVERY_LINE_REMAP_WARNING = "Recovered by remapping stale line anchors to unchanged current lines (file changed since the tagged read). Verify the diff matches your intent.";
 /**
  * `insert head:`/`insert tail:` applied despite a stale snapshot tag.
  * Head/tail position is content-independent, so drift is non-fatal: apply

package/dist/types/recovery.d.ts

@@ -17,11 +17,15 @@ export interface RecoveryResult {
 /**
  * Stateless recovery driver over a {@link SnapshotStore}. Construct once and
  * call {@link Recovery.tryRecover} per stale-tag incident. The default
- * implementation tries two strategies in order:
+ * implementation tries three strategies in order:
  *
  * 1. Apply the edits on the full-file version the tag names, then 3-way-merge
  *    the resulting patch onto the live content (handles external writes).
- * 2. (Session chain) If that version wasn't the head, replay the edits onto
+ * 2. Remap every stale anchor through the unchanged-line diff from the tagged
+ *    snapshot to the live text, then replay on live content. This handles a
+ *    prior insertion/deletion before the target while refusing changed anchors
+ *    and mixed offsets across the same edit range.
+ * 3. (Session chain) If that version wasn't the head, replay the edits onto
  *    the live content directly when line counts match AND every edit's anchor
  *    line content is unchanged between version and current — a prior in-session
  *    edit advanced the tag and the model's anchors still name the same logical

package/dist/types/snapshots.d.ts

@@ -23,14 +23,36 @@ export interface Snapshot {
 }
 /**
  * Storage seam for full-file version snapshots. The patcher calls {@link head}
- * for the latest version of a path and {@link byHash} when it needs the
+ * for the latest version of a path and {@link byHashExact} when it needs the
  * specific historical version a section's stale tag names.
  */
 export declare abstract class SnapshotStore {
     /** Most-recently recorded version for `path`, or `null` if none. */
     abstract head(path: string): Snapshot | null;
-    /** Recorded version for `path` whose tag equals `hash`, or `null`. */
+    /**
+     * 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}).
+     */
     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.
+     */
+    abstract byContent(path: string, fullText: string): Snapshot | null;
     /**
      * Every retained version whose tag equals `hash`, across all tracked
      * paths. The patcher uses this to recover the intended file when a section
@@ -84,13 +106,18 @@ export interface InMemorySnapshotStoreOptions {
  *
  * Recording byte-identical content again refreshes recency and reuses the
  * existing tag (read fusion); recording new content unshifts a fresh version
- * onto the front of the path history.
+ * onto the front of the path history. Two distinct texts that collide on the
+ * short 4-hex tag are retained as separate versions so callers can still tell
+ * them apart via {@link Snapshot.text} — the tag is only a fast index, never
+ * the identity.
  */
 export declare class InMemorySnapshotStore extends SnapshotStore {
     #private;
     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;
     recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "16.2.12",
+	"version": "16.3.0",
 	"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

@@ -54,7 +54,7 @@ export const BARE_BODY_AUTO_PIPED_WARNING =
 
 /** Unified-diff-style `-` row in a hunk body. */
 export const MINUS_ROW_REJECTED =
-	"`-` rows are not valid; the range already names the lines being changed. For a literal `-` line, write `+-…`.";
+	"`-` rows are not valid; the range already names the lines being changed. For Markdown bullets or other literal `-` lines, prefix the literal row with `+`: `+- item`.";
 
 /** Replace hunk with no body. */
 export const EMPTY_REPLACE = `\`SWAP N${HL_RANGE_SEP}M:\` needs at least one \`+TEXT\` body row. To delete lines, use \`DEL N${HL_RANGE_SEP}M\`.`;
@@ -168,6 +168,10 @@ export const RECOVERY_SESSION_CHAIN_WARNING =
 export const RECOVERY_SESSION_REPLAY_WARNING =
 	"Recovered by replaying your edits onto the current file content (a prior in-session edit changed the lines you re-targeted with a stale hash). Verify the diff matches your intent.";
 
+/** `Recovery`: stale anchors were relocated to unchanged live lines after drift. */
+export const RECOVERY_LINE_REMAP_WARNING =
+	"Recovered by remapping stale line anchors to unchanged current lines (file changed since the tagged read). Verify the diff matches your intent.";
+
 /**
  * `insert head:`/`insert tail:` applied despite a stale snapshot tag.
  * Head/tail position is content-independent, so drift is non-fatal: apply

package/src/patcher.ts

@@ -38,7 +38,7 @@ import {
 import { MismatchError } from "./mismatch";
 import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { Recovery, type RecoveryResult } from "./recovery";
-import type { SnapshotStore } from "./snapshots";
+import type { Snapshot, SnapshotStore } from "./snapshots";
 import type { ApplyResult, BlockResolution, BlockResolver, Edit, FileOp } from "./types";
 
 export interface PatcherOptions {
@@ -480,14 +480,15 @@ export class Patcher {
 
 	/**
 	 * Reject an anchored edit that references a line the read which minted
-	 * `expected` never displayed. The snapshot's `seenLines` is the set of
-	 * 1-indexed lines a producer (read/search) actually showed under that tag;
-	 * absent or empty means no provenance was recorded, so the edit applies as
-	 * before. Only runs on the no-drift path, where anchor line numbers index
-	 * the tagged content 1:1.
+	 * `expected` never displayed. `matchedSnapshot` is the store version whose
+	 * text equals the live normalized content — the exact snapshot the model
+	 * anchored against. Absent means no provenance was recorded (the tag was
+	 * 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.
 	 */
-	#assertSeenLines(section: PatchSection, canonicalPath: string, expected: string): void {
-		const seen = this.snapshots.byHash(canonicalPath, expected)?.seenLines;
+	#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;
@@ -520,7 +521,23 @@ export class Patcher {
 	}): ApplyResult {
 		const { section, canonicalPath, exists, normalized, edits } = args;
 		const expected = exists ? section.fileHash : undefined;
-		const liveMatches = expected !== undefined && computeFileHash(normalized) === expected;
+		// 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;
+		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);
 
 		// Resolve `replace_block N:` edits to concrete ranges before recovery
 		// runs. Block anchors are expressed against the snapshot the section tag
@@ -535,8 +552,10 @@ export class Patcher {
 		const resolveWarnings: string[] = [];
 		let resolved: readonly Edit[] = edits;
 		if (hasBlockEdit(edits)) {
-			const baseText =
-				expected === undefined || liveMatches ? normalized : this.snapshots.byHash(canonicalPath, expected)?.text;
+			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);
 			}
@@ -559,7 +578,7 @@ export class Patcher {
 			// The line numbers in `edits` index the exact content the tag names.
 			// Reject any anchor the read never displayed: editing lines the model
 			// has not seen is the off-by-memory mistake that mangles files.
-			if (expected !== undefined) this.#assertSeenLines(section, canonicalPath, expected);
+			if (expected !== undefined) this.#assertSeenLines(section, expected, matchedSnapshot);
 			const result = applyEdits(normalized, resolved);
 			return withResolveWarnings(blockResolutions.length > 0 ? { ...result, blockResolutions } : result);
 		}
@@ -571,6 +590,9 @@ 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/prompt.md

@@ -19,7 +19,7 @@ Single line: `SWAP N.=N:` / `DEL N`. The range is the ORIGINAL lines you touch;
 </ops>
 
 <body-rows>
-Body rows appear only under a `:` header. Every body row is `+TEXT` — add a literal line `TEXT`, verbatim (leading whitespace kept); `+` alone adds a blank line. No other row kind. NEVER write `-old` or a bare/context line. To keep a line, leave it out of every range. To insert a literal line starting with `-` or `+`, prefix it: `+-x`, `++x`.
+Body rows appear only under a `:` header. Every body row is `+TEXT` — add a literal line `TEXT`, verbatim (leading whitespace kept); `+` alone adds a blank line. No other row kind. NEVER write `-old` or a bare/context line. To keep a line, leave it out of every range. Literal lines starting with `-`/`+` still need the body prefix: Markdown `- item` → `+- item`, `+ item` → `++ item`.
 </body-rows>
 
 <rules>
@@ -103,6 +103,14 @@ INS.TAIL:
 +greet("everyone")
 ```
 
+Insert Markdown bullets — the leading `+` is the body-row marker; the file receives `- task`:
+```
+[PLAN.md#A1B2]
+INS.POST 2:
++- task
++  - nested task
+```
+
 Replace the whole `greet` function block — `SWAP.BLK 1:` resolves lines 1–3 (the `def` header through `print(msg)`); line 4 is a separate statement and stays:
 ```
 [greet.py#A1B2]
@@ -160,5 +168,5 @@ INS.POST 3:
 If you remember nothing else:
 1. RE-GROUND AFTER EVERY EDIT. Every apply mints a fresh `#TAG` and renumbers — take the next edit's numbers from the edit response or a fresh `read`. Stale tag or surprise? STOP, re-`read`.
 2. RANGES ARE TIGHT. Cover only lines that change; a stale wide range shreds everything it spans. Whole construct → `SWAP.BLK N`.
-3. THE BODY IS THE FINAL CONTENT. Only `+TEXT` rows; never `-old`/context lines. The range does the deleting.
+3. THE BODY IS THE FINAL CONTENT. Every body row starts with `+`; Markdown bullets use `+- item`, not `- item`.
 </critical>

package/src/recovery.ts

@@ -10,7 +10,12 @@
  */
 import * as Diff from "diff";
 import { applyEdits } from "./apply";
-import { RECOVERY_EXTERNAL_WARNING, RECOVERY_SESSION_CHAIN_WARNING, RECOVERY_SESSION_REPLAY_WARNING } from "./messages";
+import {
+	RECOVERY_EXTERNAL_WARNING,
+	RECOVERY_LINE_REMAP_WARNING,
+	RECOVERY_SESSION_CHAIN_WARNING,
+	RECOVERY_SESSION_REPLAY_WARNING,
+} from "./messages";
 import type { Snapshot, SnapshotStore } from "./snapshots";
 import type { Anchor, ApplyResult, Edit } from "./types";
 
@@ -97,6 +102,219 @@ function verifyAnchorContent(previousText: string, currentText: string, edits: r
 	return true;
 }
 
+function buildLineMap(previousText: string, currentText: string): Map<number, number> {
+	const previousLines = previousText.split("\n");
+	const currentLines = currentText.split("\n");
+	const changes = Diff.diffArrays(previousLines, currentLines);
+	const map = new Map<number, number>();
+	let previousLine = 1;
+	let currentLine = 1;
+
+	for (const change of changes) {
+		const count = change.value.length;
+		if (change.added) {
+			currentLine += count;
+			continue;
+		}
+		if (change.removed) {
+			previousLine += count;
+			continue;
+		}
+		for (let offset = 0; offset < count; offset++) {
+			map.set(previousLine + offset, currentLine + offset);
+		}
+		previousLine += count;
+		currentLine += count;
+	}
+
+	return map;
+}
+
+/** Values appearing two or more times in `lines`, for O(1) duplicate checks. */
+function collectDuplicatedValues(lines: readonly string[]): Set<string> {
+	const seen = new Set<string>();
+	const duplicated = new Set<string>();
+	for (const value of lines) {
+		if (seen.has(value)) duplicated.add(value);
+		else seen.add(value);
+	}
+	return duplicated;
+}
+
+interface AnchorNeighbors {
+	/** Nearest non-anchor line below the anchor's run, or `undefined` at the file edge. */
+	before: number | undefined;
+	/** Nearest non-anchor line above the anchor's run, or `undefined` at the file edge. */
+	after: number | undefined;
+}
+
+/**
+ * Nearest non-anchor context line on each side of every anchor, computed in
+ * one sweep over the sorted anchor set. Anchors in one contiguous run share
+ * both neighbors (the lines just outside the run), so this replaces the
+ * per-anchor directional walk across anchored ranges — O(anchors²) on a
+ * large block replacement — with one O(anchors log anchors) pass.
+ */
+function computeAnchorNeighbors(anchorLines: ReadonlySet<number>, lineCount: number): Map<number, AnchorNeighbors> {
+	const sorted = [...anchorLines].sort((a, b) => a - b);
+	const neighbors = new Map<number, AnchorNeighbors>();
+	for (let i = 0; i < sorted.length; ) {
+		let j = i;
+		while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1) j++;
+		const start = sorted[i];
+		const end = sorted[j];
+		const before = start - 1 >= 1 && start - 1 <= lineCount ? start - 1 : undefined;
+		const after = end + 1 <= lineCount ? end + 1 : undefined;
+		for (let k = i; k <= j; k++) neighbors.set(sorted[k], { before, after });
+		i = j + 1;
+	}
+	return neighbors;
+}
+
+function validateDuplicateAnchorContext(
+	line: number,
+	mapped: number,
+	neighbors: AnchorNeighbors,
+	lineMap: ReadonlyMap<number, number>,
+): boolean {
+	let checked = false;
+	const { before, after } = neighbors;
+	if (before !== undefined) {
+		checked = true;
+		if (lineMap.get(before) !== mapped - (line - before)) return false;
+	}
+	if (after !== undefined) {
+		checked = true;
+		if (lineMap.get(after) !== mapped + (after - line)) return false;
+	}
+	return checked;
+}
+
+function validateUniqueAnchorContext(
+	line: number,
+	mapped: number,
+	neighbors: AnchorNeighbors,
+	lineMap: ReadonlyMap<number, number>,
+): boolean {
+	const offset = mapped - line;
+	const { before, after } = neighbors;
+	if (after !== undefined) return lineMap.get(after) === after + offset;
+	return before !== undefined && lineMap.get(before) === before + offset;
+}
+
+function validateRemappedAnchorContext(
+	previousText: string,
+	currentText: string,
+	lineMap: ReadonlyMap<number, number>,
+	edits: readonly Edit[],
+): boolean {
+	const previousLines = previousText.split("\n");
+	const currentLines = currentText.split("\n");
+	const anchorLines = new Set(collectAnchorLines(edits));
+	// Precompute once per validation pass: which line values are duplicated,
+	// and each anchor's nearest non-anchor context. The per-anchor forms —
+	// indexOf/lastIndexOf full-file scans plus directional walks across
+	// anchored ranges — are O(anchors×lines) + O(anchors²) and blow up on
+	// large block replacements.
+	const duplicatedPrevious = collectDuplicatedValues(previousLines);
+	const duplicatedCurrent = collectDuplicatedValues(currentLines);
+	const anchorNeighbors = computeAnchorNeighbors(anchorLines, previousLines.length);
+
+	for (const [line, neighbors] of anchorNeighbors) {
+		const mapped = lineMap.get(line);
+		if (mapped === undefined) return false;
+		if (!duplicatedPrevious.has(previousLines[line - 1]) && !duplicatedCurrent.has(currentLines[mapped - 1])) {
+			if (!validateUniqueAnchorContext(line, mapped, neighbors, lineMap)) {
+				return false;
+			}
+			continue;
+		}
+		if (!validateDuplicateAnchorContext(line, mapped, neighbors, lineMap)) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+function remapEditsToCurrent(previousText: string, currentText: string, edits: readonly Edit[]): Edit[] | null {
+	const lineMap = buildLineMap(previousText, currentText);
+	if (!validateRemappedAnchorContext(previousText, currentText, lineMap, edits)) return null;
+	const offsets: number[] = [];
+
+	const mapLine = (line: number): number | null => {
+		const mapped = lineMap.get(line);
+		if (mapped === undefined) return null;
+		offsets.push(mapped - line);
+		return mapped;
+	};
+
+	const mapAnchor = (anchor: Anchor): Anchor | null => {
+		const line = mapLine(anchor.line);
+		return line === null ? null : { line };
+	};
+
+	const remapped: Edit[] = [];
+	for (const edit of edits) {
+		if (edit.kind === "delete") {
+			const anchor = mapAnchor(edit.anchor);
+			if (anchor === null) return null;
+			remapped.push({ ...edit, anchor });
+			continue;
+		}
+		if (edit.kind === "block") {
+			const anchor = mapAnchor(edit.anchor);
+			if (anchor === null) return null;
+			remapped.push({ ...edit, anchor });
+			continue;
+		}
+
+		let blockStart = edit.blockStart;
+		if (blockStart !== undefined) {
+			const mappedBlockStart = mapLine(blockStart);
+			if (mappedBlockStart === null) return null;
+			blockStart = mappedBlockStart;
+		}
+
+		const cursor = edit.cursor;
+		if (cursor.kind !== "before_anchor" && cursor.kind !== "after_anchor") {
+			remapped.push(blockStart === edit.blockStart ? edit : { ...edit, blockStart });
+			continue;
+		}
+
+		const anchor = mapAnchor(cursor.anchor);
+		if (anchor === null) return null;
+		remapped.push({ ...edit, cursor: { kind: cursor.kind, anchor }, blockStart });
+	}
+
+	if (offsets.length === 0) return null;
+	const firstOffset = offsets[0];
+	if (firstOffset === 0) return null;
+	if (!offsets.every(offset => offset === firstOffset)) return null;
+	return remapped;
+}
+
+function replayRemappedAnchorsOnCurrent(
+	previousText: string,
+	currentText: string,
+	edits: readonly Edit[],
+): RecoveryResult | null {
+	const remapped = remapEditsToCurrent(previousText, currentText, edits);
+	if (remapped === null) return null;
+	let applied: ApplyResult;
+	try {
+		applied = applyEdits(currentText, remapped);
+	} catch {
+		return null;
+	}
+	if (applied.text === currentText) return null;
+	return {
+		text: applied.text,
+		firstChangedLine: applied.firstChangedLine,
+		warnings: [RECOVERY_LINE_REMAP_WARNING, ...(applied.warnings ?? [])],
+	};
+}
+
 function replaySessionChainOnCurrent(
 	previousText: string,
 	currentText: string,
@@ -150,11 +368,15 @@ function isHeadSnapshot(head: Snapshot | null, snapshot: Snapshot): boolean {
 /**
  * Stateless recovery driver over a {@link SnapshotStore}. Construct once and
  * call {@link Recovery.tryRecover} per stale-tag incident. The default
- * implementation tries two strategies in order:
+ * implementation tries three strategies in order:
  *
  * 1. Apply the edits on the full-file version the tag names, then 3-way-merge
  *    the resulting patch onto the live content (handles external writes).
- * 2. (Session chain) If that version wasn't the head, replay the edits onto
+ * 2. Remap every stale anchor through the unchanged-line diff from the tagged
+ *    snapshot to the live text, then replay on live content. This handles a
+ *    prior insertion/deletion before the target while refusing changed anchors
+ *    and mixed offsets across the same edit range.
+ * 3. (Session chain) If that version wasn't the head, replay the edits onto
  *    the live content directly when line counts match AND every edit's anchor
  *    line content is unchanged between version and current — a prior in-session
  *    edit advanced the tag and the model's anchors still name the same logical
@@ -170,16 +392,26 @@ export class Recovery {
 	 */
 	tryRecover(args: RecoveryArgs): RecoveryResult | null {
 		const { path, currentText, fileHash, edits } = args;
-		const snapshot = this.store.byHash(path, fileHash);
+		// 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);
 		if (!snapshot) return null;
 		const isHead = isHeadSnapshot(this.store.head(path), snapshot);
 		const recoveryWarning = isHead ? RECOVERY_EXTERNAL_WARNING : RECOVERY_SESSION_CHAIN_WARNING;
 		const merged = applyEditsToSnapshot(snapshot.text, currentText, edits, recoveryWarning);
 		if (merged !== null) return merged;
-		// Session-chain fallback: the 3-way merge on the version refused.
-		// Replay onto current is gated by line-count equality AND
-		// anchor-content alignment — see `replaySessionChainOnCurrent`
-		// for why both guards together still don't fully prove correctness.
+		// Line-shift fallback: the 3-way merge refused, but unchanged anchor
+		// lines may have moved because a prior edit inserted or deleted rows
+		// before them. Remap only when every anchor resolves through the diff
+		// with one consistent offset; otherwise the edit range was touched.
+		const remapped = replayRemappedAnchorsOnCurrent(snapshot.text, currentText, edits);
+		if (remapped !== null) return remapped;
+		// Session-chain fallback: replay onto current is gated by line-count
+		// equality AND anchor-content alignment — see
+		// `replaySessionChainOnCurrent` for why both guards together still
+		// don't fully prove correctness.
 		if (!isHead) return replaySessionChainOnCurrent(snapshot.text, currentText, edits);
 		return null;
 	}

package/src/snapshots.ts

@@ -10,9 +10,9 @@
  * Producers (typically `read` / `search` / `write` tools) call
  * {@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 (the patcher) resolve a stale tag back to the recorded full
- * text via {@link SnapshotStore.byHash} and 3-way-merge the would-be edit onto
- * the live content.
+ * tag. Consumers (recovery, the patcher) resolve a stale tag back to the
+ * recorded full text via {@link SnapshotStore.byHashExact} and 3-way-merge the
+ * would-be edit onto the live content.
  *
  * The abstract base class lets callers plug in whatever storage they like
  * (LRU, persistent SQLite, etc.). {@link InMemorySnapshotStore} ships as a
@@ -49,16 +49,40 @@ export interface Snapshot {
 
 /**
  * Storage seam for full-file version snapshots. The patcher calls {@link head}
- * for the latest version of a path and {@link byHash} when it needs the
+ * for the latest version of a path and {@link byHashExact} when it needs the
  * specific historical version a section's stale tag names.
  */
 export abstract class SnapshotStore {
 	/** Most-recently recorded version for `path`, or `null` if none. */
 	abstract head(path: string): Snapshot | null;
 
-	/** Recorded version for `path` whose tag equals `hash`, or `null`. */
+	/**
+	 * 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}).
+	 */
 	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.
+	 */
+	abstract byContent(path: string, fullText: string): Snapshot | null;
+
 	/**
 	 * Every retained version whose tag equals `hash`, across all tracked
 	 * paths. The patcher uses this to recover the intended file when a section
@@ -133,7 +157,10 @@ export interface InMemorySnapshotStoreOptions {
  *
  * Recording byte-identical content again refreshes recency and reuses the
  * existing tag (read fusion); recording new content unshifts a fresh version
- * onto the front of the path history.
+ * onto the front of the path history. Two distinct texts that collide on the
+ * short 4-hex tag are retained as separate versions so callers can still tell
+ * them apart via {@link Snapshot.text} — the tag is only a fast index, never
+ * the identity.
  */
 export class InMemorySnapshotStore extends SnapshotStore {
 	readonly #versions: LRUCache<string, Snapshot[]>;
@@ -162,6 +189,25 @@ 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;
+	}
+
 	findByHash(hash: string): Snapshot[] {
 		const matches: Snapshot[] = [];
 		for (const history of this.#versions.values()) {
@@ -176,7 +222,13 @@ export class InMemorySnapshotStore extends SnapshotStore {
 		const hash = computeFileHash(fullText);
 		// `get` refreshes LRU recency for `path`.
 		const history = this.#versions.get(path) ?? [];
-		const existing = history.find(version => version.hash === hash);
+		// Dedup requires full-text equality, not just tag equality: two distinct
+		// texts that happen to share the 4-hex tag are DIFFERENT snapshots — fusing
+		// them under one entry would corrupt seenLines (attaching lines from
+		// text B onto the stored text A) and let the patcher misresolve which
+		// snapshot the section tag names when it does 3-way merge or seen-line
+		// validation. See issue #4075.
+		const existing = history.find(version => version.hash === hash && version.text === fullText);
 		if (existing) {
 			// Same content state observed again: refresh recency and promote to
 			// head (it is the current file content), then reuse the tag. Union any